Merge pull request #65 from getsentry/feature/improved-linking

Improve react-native link

docs/index.rst

@@ -5,143 +5,95 @@
 React Native
 ============
 
-This is the documentation for our beta clients for React-Native.  This is
-an early release with various different levels of support.  iOS is best
-supported if you are also using the native extension and if not we fall
-back to pure JavaScript for basic support.
-
-We would love to get your feedback!
+This is the documentation for our beta clients for React-Native.  The
+React-Native client uses a native extension for iOS and Android but can
+fall back to a pure JavaScript version if needed.
 
 Installation
 ------------
 
-Start with adding sentry and linking it::
+Start by adding Sentry and then linking it::
 
     $ npm install react-native-sentry --save
     $ react-native link react-native-sentry
 
-The `link` step will pull in the native dependency.  If you are using
-expo you don't have to (or can't) run that step.  In that case we fall
-back automatically.
+The `link` step will pull in the native dependency and patch your project
+accordingly.  If you are using expo you don't have to (or can't) run that
+link step.  For more information about that see :doc:`expo`.
+
+On linking you will automatically be prompted for your DSN and other
+information and we will configure your app automatically for react-native
+and change files accordingly.  You will need to provide the following
+data: your DSN, the slug of your organization in Sentry, the slug of your
+project in Sentry as well as the API key.
+
+You can find the slugs in the URL of your project
+(``sentry.io/your-org-slug/your-project-slug``) If you don't have an auth
+token yet you can `create an auth token here <https://sentry.io/api/>`_.
 
-On linking you will usually be prompted for your DSN and we will configure
-your app automatically for react-native and change files accordingly.
 Upon linking the following changes will be performed:
 
-* added the raven-java package for native crash reporting on android
-* added the sentry-swift package for native crash reporting on iOS
-* enabled the sentry gradle build step for android
+* add the raven-java package for native crash reporting on Android
+* add the sentry-swift package for native crash reporting on iOS
+* enable the sentry gradle build step for android
 * patch `AppDelegate.m` for iOS
 * patch `MainApplication.java` for Android
-* configured Sentry for the supplied DSN in your `index.js` files
+* configure Sentry for the supplied DSN in your `index.js` files
+* store build credentials in `ios/sentry.properties` and
+  `android/sentry.properties`.
+
+To see what is happening during linking you can refer to
+:doc:`manual-setup` which will give you all the details.
 
 Note that we only support ``react-native >= 0.38`` at the moment.
 
+Upgrading
+---------
+
+If you are upgrading from an earlier version of sentry-react-native you
+should re-link the package to ensure the generated code is updated to the
+latest version::
+
+    $ react-native unlink react-native-sentry
+    $ react-native link react-native-sentry
+
 iOS Specifics
 -------------
 
 Since we use our `Swift Client
 <https://github.com/getsentry/sentry-swift>`_ in the background, your
-project has to embed the swift standard libraries.
-
-Search for ``ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES`` in your Xcode project
-build settings and set it to ``YES``.
-
-You will get this error message if you forget to set it::
-
-    dyld: Library not loaded: @rpath/libswiftCore.dylib
-    Referenced from: [Redacted]/Sentry.framework/Sentry
-    Reason: image not found
-
-Also note that if you build the project without setting this, you have to
-run clean in order to make the change work.
+project has to embed the swift standard libraries.  The link step will do
+this automatically for your project.
 
 When you use xcode you can hook directly into the build process to upload
-debug symbols.  Open up your xcode project in the iOS folder, go to your
-project's target and change the "Bundle React Native code and images"
-build script.  The script that is currently there needs to be adjusted as
-follows::
-
-    export SENTRY_ORG=___ORG_NAME___
-    export SENTRY_PROJECT=___PROJECT_NAME___
-    export SENTRY_AUTH_TOKEN=YOUR_AUTH_TOKEN
-    export NODE_BINARY=node
-    ../node_modules/react-native-sentry/bin/bundle-frameworks
-    ../node_modules/sentry-cli-binary/bin/sentry-cli react-native-xcode \
-      ../node_modules/react-native/packager/react-native-xcode.sh
-    ../node_modules/sentry-cli-binary/bin/sentry-cli upload-dsym
-
-You can find the slugs in the URL of your project
-(sentry.io/your-org-slug/your-project-slug) If you don't have an auth
-token yet you can `create an auth token here <https://sentry.io/api/>`_.
-
-This also uploads debug symbols in the last line which however will not
-work for bitcode enabled builds.  If you are using bitcode you need to
-remove that line (``../node_modules/sentry-cli-binary/bin/sentry-cli
-upload-dsym``) and consult the documentation on dsym handling instead (see
-:ref:`dsym-with-bitcode`).
-
-Note that uploading of debug simulator builds by default is disabled for
-speed reasons.  If you do want to also generate debug symbols for debug
-builds you can pass `--allow-fetch` as a parameter to ``react-native-xcode``.
+debug symbols and sourcemaps.  If you however are using bitcode you will
+need to disable the "Upload Debug Symbols to Sentry" build phase and then
+separately upload debug symbols from iTunes Connect to Sentry.
 
 Android Specifics
 -----------------
 
 For Android we hook into gradle for the sourcemap build process.  When you
-run ``react-native link`` the gradle files are automatically updated but
-in case you are not using linked frameworks you might have to do it
-manually.  Whenever you run ``./gradlew assembleRelease`` sourcemaps are
-automatically built and uploaded to Sentry.
-
-To enable the gradle integration you need to change your
-``android/app/build.gradle`` file and add the following line after the
-``react.gradle`` one::
-
-    apply from: "../../node_modules/react-native-sentry/sentry.gradle"
-
-Additionally you need to create an ``android/sentry.properties`` file with
-the access credentials:
-
-.. sourcecode:: ini
-
-    defaults.org=___ORG_NAME___
-    defaults.project=___PROJECT_NAME___
-    auth.token=YOUR_AUTH_TOKEN
+run ``react-native link`` the gradle files are automatically updated.
+When you run ``./gradlew assembleRelease`` sourcemaps are automatically
+built and uploaded to Sentry.
 
 Client Configuration
 --------------------
 
-Note: When you run ``react-native link`` we will attempt to automatically
-patch your code so you might notice that some of these changes were
-already performed.
-
-Add Sentry to your `index.ios.js` and `index.android.js`:
+Note: When you run ``react-native link`` we will automatically update your
+`index.ios.js` / `index.android.js` with the following changes:
 
 .. sourcecode:: javascript
 
     import { Sentry } from 'react-native-sentry';
-
     Sentry.config('___DSN___').install();
 
-If you are using the binary version of the package (eg: you ran
-``react-native link``) then you additionally need to register the native
-crash handler in your `AppDelegate.m` after the root view was created for
-iOS:
-
-.. sourcecode:: objc
-
-    #if __has_include(<React/RNSentry.h>)
-    #import <React/RNSentry.h> // This is used for versions of react >= 0.40
-    #else
-    #import "RNSentry.h" // This is used for versions of react < 0.40
-    #endif
-
-    /* in your didFinishLaunchingWithOptions */
-    [RNSentry installWithRootView:rootView];
+You can pass additional configuration options to the `config()` method if
+you want to do so.
 
-More
-----
+Deep Dive
+---------
 
 .. toctree::
    :maxdepth: 2
@@ -150,3 +102,4 @@ More
    expo
    sourcemaps
    cocoapods
+   manual-setup

docs/manual-setup.rst

@@ -0,0 +1,71 @@
+Manual Setup
+============
+
+If you can't (or don't want) to run the linking step you can see here what
+is happening on each platform.
+
+iOS
+---
+
+Since we use our `Swift Client
+<https://github.com/getsentry/sentry-swift>`_ in the background, your
+project has to embed the swift standard libraries.
+
+Xcode Settings
+``````````````
+
+The link step sets ``ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES`` in your Xcode
+project's build settings to ``YES``.
+
+You will get this error message if that setting is not set::
+
+    dyld: Library not loaded: @rpath/libswiftCore.dylib
+    Referenced from: [Redacted]/Sentry.framework/Sentry
+    Reason: image not found
+
+Build Steps
+```````````
+
+When you use Xcode you can hook directly into the build process to upload
+debug symbols.  When linking one build phase script is changed and two more
+are added.
+
+We modify the react-native build phase ("Bundle React Native code and images")
+slightly from this::
+
+    export NODE_BINARY=node
+    ../node_modules/react-native/packager/react-native-xcode.sh
+
+To this::
+
+    export NODE_BINARY=node
+    export SENTRY_PROPERTIES=sentry.properties
+    ../node_modules/sentry-cli-binary/bin/sentry-cli react-native-xcode \
+      ../node_modules/react-native/packager/react-native-xcode.sh
+
+Additionally we add a build script called "Bundle react-native-sentry
+Frameworks" which bundles necessary frameworks as well as a build
+step called "Upload Debug Symbols to Sentry" which uploads debug symbols
+to Sentry.  The latter needs to be disabled if you use bitcode.
+
+This also uploads debug symbols in the last line which however will not
+work for bitcode enabled builds.  If you are using bitcode you need to
+remove that line (``../node_modules/sentry-cli-binary/bin/sentry-cli
+upload-dsym``) and consult the documentation on dsym handling instead (see
+:ref:`dsym-with-bitcode`).
+
+Note that uploading of debug simulator builds by default is disabled for
+speed reasons.  If you do want to also generate debug symbols for debug
+builds you can pass `--allow-fetch` as a parameter to ``react-native-xcode``
+in the above mentioned build phase.
+
+Android
+-------
+
+For Android we hook into gradle for the sourcemap build process.  When you
+run ``react-native link`` the gradle files are automatically updated.
+
+We enable the gradle integration in your ``android/app/build.gradle`` file
+by adding the following line after the ``react.gradle`` one::
+
+    apply from: "../../node_modules/react-native-sentry/sentry.gradle"

package.json

@@ -20,10 +20,12 @@
     "react-native": ">=0.38.0"
   },
   "dependencies": {
+    "chalk": "^1.1.1",
+    "glob": "7.1.1",
+    "inquirer": "3.0.6",
     "raven-js": "^3.15.0",
     "sentry-cli-binary": "^1.9.0",
-    "inquirer": "3.0.6",
-    "glob": "7.1.1"
+    "xcode": "0.9.3"
   },
   "rnpm": {
     "commands": {