Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update building.md with updated instructions, point README to building.md #4004

Merged
merged 6 commits into from
Oct 11, 2021
Merged

Update building.md with updated instructions, point README to building.md #4004

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift click to select a range
26dd269
Update building.md with updated instructions, point README to it
Oct 6, 2021
3f1bc9c
Split out sample app workflow into its own file
Oct 6, 2021
61f06ae
Update TOC
Oct 6, 2021
eada617
Add information on legacy vs modern tests
Oct 7, 2021
dac007d
fixup! Update building.md with updated instructions, point README to it
Oct 7, 2021
02ad469
Add template apps to README
Oct 8, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Split out sample app workflow into its own file
  • Loading branch information
Tom Duncalf committed Oct 6, 2021
commit 3f1bc9c0c7faa21e331591b3bb831b5f9e2b0749
207 changes: 5 additions & 202 deletions contrib/building.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 11,7 @@
* [Building the documentation](#building-the-documentation)
* [Running the tests](#running-the-tests)
* [Debugging the tests](#debugging-the-tests)
* [Sample projects for testing changes](#sample-projects-for-testing-changes)
* [Testing workflow suggestion with sample apps](#testing-workflow-suggestion-with-sample-apps)
* [Testing against real apps](#testing-against-real-apps)
<!--te-->

## Pre-Requisites
Expand Down Expand Up @@ -281,205 280,9 @@ Prior to begin debugging, you must start Realm Object Server. In VSCode, under m

In the debugging pane, you can find `Debug LLDB Node.js` in the dropdown. First select *Start Debugging* in the *Debug* menu.

## Sample projects for testing changes
## Testing against real apps

To test your changes on React Native you can clone this sample project:
There are a couple of suggested workflows for testing your changes to Realm JS against real apps:

```sh
git clone https://github.com/cesarvr/react-native-realm sample-rn-project
cd sample-rn-project
npm install
```

To test your changes on Node.js you can clone this sample project:

```sh
git clone https://github.com/cesarvr/hello-world-realm-js hello-sync
cd hello-sync
npm install
```

## Testing workflow suggestion with sample apps

This is one suggested workflow for testing your changes against the two sample apps, making use of a script to automatically copy any changes from the `realm-js` project into the two sample projects.

### Deploying Changes

Right now you should have three folders:

```sh
realm-js # realm-js source code.

hello-sync # Node.js project using realm.
sample-rn-project # the sample react-native project.
```

What you want to do is to do all your work on the `realm-js` project and use the other two projects to test and deploy any new changes.

To do that you can use the help of this tool:

```sh
cd realm-js # Jump to the realm-js root folder.
curl https://raw.githubusercontent.com/cesarvr/dev-lnk/master/index.js -o nlk.js # Download the file in there.
```

You can configure this tool to watch some sections of your ``realm-js`` and deploy those changes automatically to any of those projects.

Once you have the script you just need to go to the bottom and configure the files/folder you want to watch and update in your target, something similar to this:

```js
syncByAppend(
'<source-folder>', // Source folder...
'<target-folder>', // Target folder...
<RegExp> /* Regular expression to match and update */
)
```

### Android

First let's configure the ```nlk.js``` tool to watch for Android changes and deploy this into the React Native project.

Open ```nlk.js``` with your favourite text editor like ``vim``, go to the bottom and add:

```js
syncByAppend(
'./react-native/android/build/realm-react-ndk/all', // Source folder...
'../sample-rn-project/node_modules/realm/android/src/main/jniLibs', // Target folder...
RegExp('librealmreact.so')) // copy librealmreact.so if a change has been detected...
```

> As you can see this is just a dumb script that copy files anytime they change... you can use [Regular Expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) to handle more complex scenarios.


After adding that you can run it by doing:

```sh
node nlk.js # it will sleep and wait for changes...
```

#### Building for Android

Open a new terminal tab and start doing your changes on the ``realm-js/src`` folder for example and once your are ready you can build an Android binary by doing:

```sh
# from the realm-js root folder...

cd react-native/android/ # enter the React Native Android project.
./gradlew publishAndroid # Take a coffee...
```

As soon as the compilation finish this module will be deployed into the React Native project (``sample-rn-project``).


If you visit the script tab you will see the files that have been sync:

```sh
sync done for: librealmreact.so. 11:54:30 # arm
sync done for: librealmreact.so. 11:54:30 # x86
sync done for: librealmreact.so. 11:54:30 # x64 ...
sync done for: librealmreact.so. 11:54:30

```
> This will trigger any time a new binary object is created...

Now you can just can navigate to the React Native project and do:

```sh
npx react-native run-android
```

### iOS

For iOS the things is a bit different as per today we don't ship a pre-compiled binary like we do on Android.

But we can keep the source files in sync between the main source of truth the ``realm-js`` folder against the iOS project embedded in the React Native project (```sample-rn-project```).

First as we did with the Android project we add a new entry to the script:

```js
// Android
syncByAppend('./react-native/android/build/realm-react-ndk/all',
'../sample-rn-project/node_modules/realm/android/src/main/jniLibs',
RegExp('librealmreact.so'))

// iOS
syncByAppend('./src',
'../sample-rn-project/node_modules/realm/src',
RegExp('.*'))
```

Now if make a change in the ```realm-js/src``` folder you will see this change propagate to your React Native project.

```sh
sync done for: js_logger.hpp. 12:54:26
sync done for: js_logger.hpp. 12:54:26
```

#### Building for iOS

Now you can just open the xcode project in ```sample-rn-project``` by doing:

```sh
cd sample-rn-project/ios/
pod install # Install iOS dependencies

open sample-rn-project/ios/MyAwesomeRealmApp.xcworkspace
#or just open MyAwesomeRealmApp.xcworkspace if you are inside the folder
```

After that you can press ```CMD B``` and see your changes compiled, then you do ```CMD R``` and you run the new code on the emulator.

### Node.js

In Node.js, we need to sync the module generated using the included Node.js [GYP](https://gyp.gsrc.io/).

Assuming we have the same folder structure:

```sh
realm-js # realm-js source code.

hello-sync # Node.js project using realm.
sample-rn-project # the sample react-native project.
```

We jump to the ``realm-js`` root folder and open the ```nlk.js``` script, jump to the bottom and add:

```js
// Android
syncByAppend('./react-native/android/build/realm-react-ndk/all',
'../sample-rn-project/node_modules/realm/android/src/main/jniLibs',
RegExp('librealmreact.so'))

// iOS
syncByAppend('./src',
'../sample-rn-project/node_modules/realm/src',
RegExp('.*'))


// Node.js [ New ]
syncByAppend('./compiled',
'../hello-sync/node_modules/realm/compiled',
RegExp('realm.node'))

```

That's it run the script to start watching/sync for files:

```sh
node nlk.js
```

#### Building for Node.js

Then once you are fine with changes, you just need to compile the Node.js module using:

```sh
npm install --build-from-source=realm # Take a coffee...

#... events from nlk ...
#sync done for: realm.node. 13:8:26
#sync done for: realm.node. 13:8:26

```

Once that finish you can go to your Node.js project (``hello-sync``) and try your changes.
* [Guide: Setting up watchman to copy changes from this package to an app](guide-watchman.md)
* [Guide: Testing your changes against sample apps using a script](guide-testing-with-sample-apps.md)
Loading