Add documentation for react-native link apart from the platform speci…

…fic iOS linking documentation, add documentation for rnpm
facebook · Jun 21, 2018 · fc21b81 · fc21b81
1 parent 5995e3d
commit fc21b81
Show file tree

Hide file tree

Showing 6 changed files with 113 additions and 88 deletions.
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -19,8 +19,8 @@ There are many ways to contribute to React Native, and many of them do not invol
 * Read through the [React Native docs](http://facebook.github.io/react-native/). If you find anything that is confusing or can be improved, you can make edits by clicking "Edit" at the top of most docs.
 * Browse [Stack Overflow](https://stackoverflow.com/questions/tagged/react-native) and answer questions. This will help you get familiarized with common pitfalls or misunderstandings, which can be useful when contributing updates to the documentation.
 * Take a look at the [features requested](https://react-native.canny.io/feature-requests) by others in the community and consider opening a pull request if you see something you want to work on.
-* Before opening your pull request, make sure you have fully tested your changes. Test your changes locally and by running the various tests provided. 
-* For information on how to build the React Native project locally with your changes, make sure to read through the [Building React Native from source guide](https://facebook.github.io/react-native/docs/building-from-source.html). 
+* Before opening your pull request, make sure you have fully tested your changes. Test your changes locally and by running the various tests provided.
+* For information on how to build the React Native project locally with your changes, make sure to read through the [Building React Native from source guide](https://facebook.github.io/react-native/docs/building-from-source.html).
 * Check out the [Testing your changes guide](https://facebook.github.io/react-native/docs/testing.html) to find out about the numerous tests which has been provided to help ensure that any new changes wont cause a regression.
 
 Contributions are very welcome. If you think you need help planning your contribution, please hop into [#react-native](https://discord.gg/0ZcbPKXt5bZjGY5n) and let people know you're looking for a mentor.

diff --git a/docs/linking-libraries-ios.md b/docs/linking-libraries-ios.md
@@ -1,41 +1,9 @@
 ---
 id: linking-libraries-ios
-title: Linking Libraries
+title: Linking Libraries (iOS)
 ---
 
-Not every app uses all the native capabilities, and including the code to support all those features would impact the binary size... But we still want to make it easy to add these features whenever you need them.
-
-With that in mind we exposed many of these features as independent static libraries.
-
-For most of the libs it will be as simple as dragging two files, sometimes a third step will be necessary, but no more than that.
-
-_All the libraries we ship with React Native live on the `Libraries` folder in the root of the repository. Some of them are pure JavaScript, and you only need to `require` it. Other libraries also rely on some native code, in that case you'll have to add these files to your app, otherwise the app will throw an error as soon as you try to use the library._
-
-## Here are the few steps to link your libraries that contain native code
-
-### Automatic linking
-
-#### Step 1
-
-Install a library with native dependencies:
-
-```bash
-$ npm install <library-with-native-dependencies> --save
-```
-
-> **_Note:_** `--save` or `--save-dev` flag is very important for this step. React Native will link your libs based on `dependencies` and `devDependencies` in your `package.json` file.
-
-#### Step 2
-
-Link your native dependencies:
-
-```bash
-$ react-native link
-```
-
-Done! All libraries with native dependencies should be successfully linked to your iOS/Android project.
-
-> **_Note:_** If your iOS project is using CocoaPods (contains `Podfile`) and linked library has `podspec` file, then `react-native link` will link library using Podfile. To support non-trivial Podfiles add `# Add new pods below this line` comment to places where you expect pods to be added.
+For most applications, [React Native's Automatic Linking](linking-libraries.md) should be sufficient. In some cases, you will not be able to automatically link, and must link your binaries by hand. For most applications this will mean dragging and dropping a handful of files, as documented below.
 
 ### Manual linking
 

diff --git a/docs/linking-libraries.md b/docs/linking-libraries.md
@@ -0,0 +1,54 @@
+---
+id: linking-libraries
+title: Linking Libraries
+---
+
+Every app is different, and some apps use device features which others do not. Having every possible feature bundled within React Native would cause your application to be too big, so by default React Native only includes the basics. Using a feature called "static linking", you can add additional native capabilities if your project needs them.
+
+React Native attempts to make static linking as easy as possible using the `react-native link` command, documented below. You can also use the native platform tools to manually link libraries (for [iOS](linking-libraries-ios.md) or [Android](native-modules-android.md)), as you might for a native-only project.
+
+_All the libraries we ship with React Native live in the `Libraries` folder in the root of the repository. Some of them are pure JavaScript, and you only need to `require` them. Other libraries also rely on native code and must be linked._
+
+## Here are the few steps to link your libraries that contain native code
+
+### Automatic linking
+
+#### Step 1
+
+Install a library with native dependencies:
+
+```bash
+$ npm install <library-with-native-dependencies> --save
+```
+
+> **_Note:_** the `--save` flag is very important for this step. React Native will only link the libraries specified within `dependencies` in your `package.json` file.
+
+#### Step 2
+
+Link your native dependencies:
+
+```bash
+$ react-native link
+```
+
+Done! All libraries with native dependencies should be successfully linked to your iOS/Android project.
+
+> **_Note:_** If your iOS project is using CocoaPods (contains `Podfile`) and linked library has `podspec` file, then `react-native link` will link library using Podfile. To support non-trivial Podfiles add `# Add new pods below this line` comment to places where you expect pods to be added.
+
+> **_Note:_** It is also possible to manually specify a library to link (instead of all libraries) with `$ npm link <library-with-native-dependencies>`
+
+### Packaging native code with your library
+
+The above is useful for people building apps with React Native, but what if you're building a library for others to use in their apps? By default, `react-native link` will link any libraries contained within the `ios` and `android` folders at the module root into the parent project.
+
+#### Copying assets
+
+To specify that the bundler should copy your custom assets you can pass an array of relative directory paths (not file paths) in the `rnpm.assets` array:
+
+```json
+...
+"rnpm": {
+  "assets": ["./fonts"]
+},
+...
+```
diff --git a/docs/removing-default-permissions.md b/docs/removing-default-permissions.md
@@ -7,63 +7,63 @@ By default, some permissions are added to your Android APK.
 
 The default permissions that get added are:
 
- * android.permission.INTERNET - Required for debug mode.
- * android.permission.SYSTEM_ALERT_WINDOW - Required for debug mode.
- * android.permission.READ_PHONE_STATE - Not required for debug or production.
- * android.permission.WRITE_EXTERNAL_STORAGE - Not required for debug or production.
- * android.permission.READ_EXTERNAL_STORAGE - Not required for debug or production.
+* android.permission.INTERNET - Required for debug mode.
+* android.permission.SYSTEM_ALERT_WINDOW - Required for debug mode.
+* android.permission.READ_PHONE_STATE - Not required for debug or production.
+* android.permission.WRITE_EXTERNAL_STORAGE - Not required for debug or production.
+* android.permission.READ_EXTERNAL_STORAGE - Not required for debug or production.
 
 1. Let's start by removing `READ_PHONE_STATE`, `WRITE_EXTERNAL_STORAGE`, and `READ_EXTERNAL_STORAGE` from both production and debug APKs, as it is not required in either. These storage permissions are still not needed if `AsyncStorage` module is in use, so it is safe to remove from both production and debug.
 2. Open your `android/app/src/main/AndroidManifest.xml` file.
 3. Even though these three permissions are not listed in the manifest they get added in. We add the three permissions with `tools:node="remove"` attribute, to make sure it gets removed during build. Note that the package identifier will be different, for below it is "com.myapp" because the project was created with `react-native init myapp`.
-  
-    ```diff
-    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
-        package="com.myappid"
-    +   xmlns:tools="http://schemas.android.com/tools"
-        >
-    
-        <uses-permission android:name="android.permission.INTERNET" />
-        <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
-    +   <uses-permission tools:node="remove" android:name="android.permission.READ_PHONE_STATE" />
-    +   <uses-permission tools:node="remove" android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
-    +   <uses-permission tools:node="remove" android:name="android.permission.READ_EXTERNAL_STORAGE" />
-    
-        <application
-          android:name=".MainApplication"
-          android:label="@string/app_name"
-          android:icon="@mipmap/ic_launcher"
-          android:allowBackup="false"
-          android:theme="@style/AppTheme">
-          <activity
-            android:name=".MainActivity"
-            android:label="@string/app_name"
-            android:configChanges="keyboard|keyboardHidden|orientation|screenSize"
-            android:windowSoftInputMode="adjustResize">
-            <intent-filter>
-                <action android:name="android.intent.action.MAIN" />
-                <category android:name="android.intent.category.LAUNCHER" />
-            </intent-filter>
-          </activity>
-          <activity android:name="com.facebook.react.devsupport.DevSettingsActivity" />
-        </application>
-    
-    </manifest>
-    ```
-    
+
+   ```diff
+   <manifest xmlns:android="http://schemas.android.com/apk/res/android"
+       package="com.myappid"
+   +   xmlns:tools="http://schemas.android.com/tools"
+       >
+
+       <uses-permission android:name="android.permission.INTERNET" />
+       <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
+   +   <uses-permission tools:node="remove" android:name="android.permission.READ_PHONE_STATE" />
+   +   <uses-permission tools:node="remove" android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
+   +   <uses-permission tools:node="remove" android:name="android.permission.READ_EXTERNAL_STORAGE" />
+
+       <application
+         android:name=".MainApplication"
+         android:label="@string/app_name"
+         android:icon="@mipmap/ic_launcher"
+         android:allowBackup="false"
+         android:theme="@style/AppTheme">
+         <activity
+           android:name=".MainActivity"
+           android:label="@string/app_name"
+           android:configChanges="keyboard|keyboardHidden|orientation|screenSize"
+           android:windowSoftInputMode="adjustResize">
+           <intent-filter>
+               <action android:name="android.intent.action.MAIN" />
+               <category android:name="android.intent.category.LAUNCHER" />
+           </intent-filter>
+         </activity>
+         <activity android:name="com.facebook.react.devsupport.DevSettingsActivity" />
+       </application>
+
+   </manifest>
+   ```
+
 4. Now let's remove `SYSTEM_ALERT_WINDOW` from the production APK only.
 5. Go to the `android/app/src/` directory. Create a new directory inside this directory, called `release`. (path: `android/app/src/release/`)
 6. Inside this `android/app/src/release/` directory create a `AndroidManifest.xml` file. (path: `android/app/src/release/AndroidManifest.xml`)
 7. Inside this file paste the following conents. Note, make sure to update your package identifier from "com.myapp" to what yours is.
 
-    ```diff
-    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
-        package="com.myapp"
-        xmlns:tools="http://schemas.android.com/tools">
-    
-        <uses-permission tools:node="remove" android:name="android.permission.SYSTEM_ALERT_WINDOW" />
-    
-    </manifest>
-    ```
-    
+   ```diff
+   <manifest xmlns:android="http://schemas.android.com/apk/res/android"
+       package="com.myapp"
+       xmlns:tools="http://schemas.android.com/tools">
+
+       <uses-permission tools:node="remove" android:name="android.permission.SYSTEM_ALERT_WINDOW" />
+
+   </manifest>
+   ```
+
 That's it. We did not remove the `INTERNET` permission as pretty much all apps use it. Now whenever you create a production APK all these 4 permissions will be removed. When you create a debug APK (`react-native run-android`) it will install the APK with only the three permissions removed, and `SYSTEM_ALERT_WINDOW` will remain.
diff --git a/website/i18n/en.json b/website/i18n/en.json
@@ -64,7 +64,8 @@
     "keyboardavoidingview": "KeyboardAvoidingView",
     "layout-props": "Layout Props",
     "layoutanimation": "LayoutAnimation",
-    "linking-libraries-ios": "Linking Libraries",
+    "linking-libraries-ios": "Linking Libraries (iOS)",
+    "linking-libraries": "Linking Libraries",
     "linking": "Linking",
     "listview": "ListView",
     "listviewdatasource": "ListViewDataSource",
@@ -95,6 +96,7 @@
     "props": "Props",
     "pushnotificationios": "PushNotificationIOS",
     "refreshcontrol": "RefreshControl",
+    "removing-default-permissions": "Removing Default Permissions",
     "running-on-device": "Running On Device",
     "running-on-simulator-ios": "Running On Simulator",
     "safeareaview": "SafeAreaView",

diff --git a/website/sidebars.json b/website/sidebars.json
@@ -34,7 +34,8 @@
       "building-for-apple-tv",
       "running-on-device",
       "upgrading",
-      "troubleshooting"
+      "troubleshooting",
+      "linking-libraries"
     ],
     "Guides (iOS)": [
       "native-modules-ios",