jens/flipper
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Split up getting started docs

Browse Source 
Summary:
This is a first step in breaking up the getting started docs.
Ultimately, the React Native Android and iOS bits will become
separate sections, too, but I won't to keep the diffs a bit smaller.
This one doesn't really do much apart from reorganising the current
content.

Reviewed By: mweststrate

Differential Revision: D20815235

fbshipit-source-id: 5c85b788211699a2a9f5808b9e2590c7db68a1c1
This commit is contained in:
Pascal Hartig
2020-04-03 06:15:39 -07:00
committed by Facebook GitHub Bot
parent 527d417ab4
commit 0a68044649
8 changed files with 228 additions and 176 deletions
Download Patch File Download Diff File Expand all files Collapse all files

115
docs/getting-started/android-native.md Normal file
View File

@@ -0,0 +1,115 @@
---
id: android-native
title: Set up your Android app
sidebar_label: Android
---
To set up Flipper for Android, you need to add the neccessary dependencies to your
app, initialize the Flipper client and enable the plugins you want to use. Optionally,
you can hook up the diagnostics Activity to help you troubleshoot connection issues.
## Dependencies
Flipper is distributed via JCenter. Add the dependencies to your `build.gradle` file.
You should also explicitly depend on [`soloader`](https://github.com/facebook/soloader)
instead of relying on transitive dependency resolution which is getting deprecated
with Gradle 5.
We provide a "no-op" implementation of some oft-used Flipper interfaces you can
use to make it easier to strip Flipper from your release builds.
```groovy
repositories {
jcenter()
}
dependencies {
debugImplementation 'com.facebook.flipper:flipper:0.35.0'
debugImplementation 'com.facebook.soloader:soloader:0.8.2'
releaseImplementation 'com.facebook.flipper:flipper-noop:0.35.0'
}
```
<div class="warning">
Please note that our `flipper-noop` package provides a limited subset of the
APIs provided by the `flipper` package and does not provide any plugin stubs.
It is recommended that you keep all Flipper instantiation code in a separate
build variant to ensure it doesn't accidentally make it into your production
builds. Check out [the sample
app](https://github.com/facebook/flipper/tree/master/android/sample/src) to
see how to organise your Flipper initialization into debug and release
variants.
Alternatively, have a look at the third-party
[flipper-android-no-op](https://github.com/theGlenn/flipper-android-no-op)
repository, which provides empty implementations for several Flipper plugins.
</div>
## Application Setup
Now you can initialize Flipper in your Application's `onCreate` method, which involves
initializing SoLoader (for loading the C++ part of Flipper) and starting a `FlipperClient`.
```java
import com.facebook.flipper.android.AndroidFlipperClient;
import com.facebook.flipper.android.utils.FlipperUtils;
import com.facebook.flipper.core.FlipperClient;
import com.facebook.flipper.plugins.inspector.DescriptorMapping;
import com.facebook.flipper.plugins.inspector.InspectorFlipperPlugin;
public class MyApplication extends Application {
@Override
public void onCreate() {
super.onCreate();
SoLoader.init(this, false);
if (BuildConfig.DEBUG && FlipperUtils.shouldEnableFlipper(this)) {
final FlipperClient client = AndroidFlipperClient.getInstance(this);
client.addPlugin(new InspectorFlipperPlugin(this, DescriptorMapping.withDefaults()));
client.start();
}
}
}
```
## Diagnostics
It's recommended that you add the following activity to the manifest, which can help diagnose integration issues and other problems:
```xml
<activity android:name="com.facebook.flipper.android.diagnostics.FlipperDiagnosticActivity"
android:exported="true"/>
```
## Android Snapshots
Feeling adventurous? We publish Android snapshot releases directly off of `master`.
You can get the latest version by adding the Maven Snapshot repository to your sources
and pointing to the most recent `-SNAPSHOT` version.
```groovy
repositories {
maven { url 'https://oss.sonatype.org/content/repositories/snapshots/' }
}
dependencies {
debugImplementation 'com.facebook.flipper:flipper:0.35.1-SNAPSHOT'
debugImplementation 'com.facebook.soloader:soloader:0.8.2'
releaseImplementation 'com.facebook.flipper:flipper-noop:0.35.1-SNAPSHOT'
}
```
## Enabling plugins
Finally, you need to add plugins to your Flipper client. Above, we have only added the Layout Inspector plugin to get you started. See [Network Plugin](setup/network-plugin.md) and [Layout Inspector Plugin](setup/layout-plugin.md) for information on how to add them, and also enable Litho or ComponentKit support. You can check the sample apps in the [GitHub repo](https://github.com/facebook/flipper) for examples of integrating other plugins.
## Having trouble?
See the [troubleshooting page](troubleshooting.html) for help with known problems.

19
docs/getting-started/index.md Normal file
View File

@@ -0,0 +1,19 @@
---
id: index
title: Desktop App
---
Flipper helps you debug Android and iOS apps running in an emulator/simulator or connected physical development devices. Flipper consists of two parts:
- The desktop app
- The native mobile SDKs for Android and iOS
To use Flipper, you need to add the mobile SDK to your app. If you are using React Native 0.62 or higher, this is largely done automatically for you.
---
The desktop part of Flipper doesn't need any particular setup. Simply download the latest build for [Mac](https://www.facebook.com/fbflipper/public/mac), [Linux](https://www.facebook.com/fbflipper/public/linux) or [Windows](https://www.facebook.com/fbflipper/public/windows) and launch it. In order to work properly, Flipper requires a working installation of the Android and (if where applicable) iOS development tools on your system, as well as the [OpenSSL](https://www.openssl.org) binary on your `$PATH`.
Once you start Flipper and launch an emulator/simulator or connect a device, you will already be able to see the device logs in Flipper. To see app specific data, you need to integrate our native SDKs with your app.
![Logs plugin](/docs/assets/initial.png)

175
docs/getting-started.md → docs/getting-started/ios-native.md
View File

@@ -1,124 +1,14 @@
--- ---
id: getting-started id: ios-native
title: Getting Started title: Set up your iOS app
sidebar_label: iOS
--- ---
Flipper helps you debug Android and iOS apps running in an emulator/simulator or connected physical development devices. Flipper consists of two parts: We support both Swift and Objective-C for Flipper with CocoaPods as build and distribution mechanism.
- The desktop app ## CocoaPods
- The native mobile SDKs for Android and iOS
To use Flipper, you need to add the mobile SDK to your app. If you are using React Native 0.62 or higher, this is largely done automatically for you. The following configuration assumed CocoaPods 1.9+.
## Setup
### Desktop app
The desktop part of Flipper doesn't need any particular setup. Simply download the latest build for [Mac](https://www.facebook.com/fbflipper/public/mac), [Linux](https://www.facebook.com/fbflipper/public/linux) or [Windows](https://www.facebook.com/fbflipper/public/windows) and launch it. In order to work properly, Flipper requires a working installation of the Android and (if where applicable) iOS development tools on your system, as well as the [OpenSSL](https://www.openssl.org) binary on your `$PATH`.
Once you start Flipper and launch an emulator/simulator or connect a device, you will already be able to see the device logs in Flipper. To see app specific data, you need to integrate our native SDKs with your app.
![Logs plugin](assets/initial.png)
## Setup your Android app
It's recommended that you add the following activity to the manifest, which can help diagnose integration issues and other problems:
```xml
<activity android:name="com.facebook.flipper.android.diagnostics.FlipperDiagnosticActivity"
android:exported="true"/>
```
Flipper is distributed via JCenter. Add the dependencies to your `build.gradle` file.
You should also explicitly depend on [`soloader`](https://github.com/facebook/soloader)
instead of relying on transitive dependency resolution which is getting deprecated
with Gradle 5.
We provide a "no-op" implementation of some oft-used Flipper interfaces you can
use to make it easier to strip Flipper from your release builds.
```groovy
repositories {
jcenter()
}
dependencies {
debugImplementation 'com.facebook.flipper:flipper:0.35.0'
debugImplementation 'com.facebook.soloader:soloader:0.8.2'
releaseImplementation 'com.facebook.flipper:flipper-noop:0.35.0'
}
```
<div class="warning">
Please note that our `flipper-noop` package provides a limited subset of the
APIs provided by the `flipper` package and does not provide any plugin stubs.
It is recommended that you keep all Flipper instantiation code in a separate
build variant to ensure it doesn't accidentally make it into your production
builds. Check out [the sample
app](https://github.com/facebook/flipper/tree/master/android/sample/src) to
see how to organise your Flipper initialization into debug and release
variants.
Alternatively, have a look at the third-party
[flipper-android-no-op](https://github.com/theGlenn/flipper-android-no-op)
repository, which provides empty implementations for several Flipper plugins.
</div>
Now you can initialize Flipper in your Application's `onCreate` method, which involves
initializing SoLoader (for loading the C++ part of Flipper) and starting a `FlipperClient`.
```java
import com.facebook.flipper.android.AndroidFlipperClient;
import com.facebook.flipper.android.utils.FlipperUtils;
import com.facebook.flipper.core.FlipperClient;
import com.facebook.flipper.plugins.inspector.DescriptorMapping;
import com.facebook.flipper.plugins.inspector.InspectorFlipperPlugin;
public class MyApplication extends Application {
@Override
public void onCreate() {
super.onCreate();
SoLoader.init(this, false);
if (BuildConfig.DEBUG && FlipperUtils.shouldEnableFlipper(this)) {
final FlipperClient client = AndroidFlipperClient.getInstance(this);
client.addPlugin(new InspectorFlipperPlugin(this, DescriptorMapping.withDefaults()));
client.start();
}
}
}
```
### Android Snapshots
Feeling adventurous? We publish Android snapshot releases directly off of `master`.
You can get the latest version by adding the Maven Snapshot repository to your sources
and pointing to the most recent `-SNAPSHOT` version.
```groovy
repositories {
maven { url 'https://oss.sonatype.org/content/repositories/snapshots/' }
}
dependencies {
debugImplementation 'com.facebook.flipper:flipper:0.35.1-SNAPSHOT'
debugImplementation 'com.facebook.soloader:soloader:0.8.2'
releaseImplementation 'com.facebook.flipper:flipper-noop:0.35.1-SNAPSHOT'
}
```
## Setup your iOS app
We support both Swift and Objective-C for Flipper with CocoaPods as build and distribution mechanism. For CocoaPods 1.9+ following is the configuration.
### CocoaPods
<!--DOCUSAURUS_CODE_TABS--> <!--DOCUSAURUS_CODE_TABS-->
<!--Objective-C--> <!--Objective-C-->
@@ -264,7 +154,7 @@ On the first run of `pod install`, `FB_SONARKIT_ENABLED=1` may not be added in t
</div> </div>
### For pure Objective-C projects ## For pure Objective-C projects
For pure Objective-C projects, add the following things in your settings: For pure Objective-C projects, add the following things in your settings:
@@ -338,51 +228,16 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
<!--END_DOCUSAURUS_CODE_TABS--> <!--END_DOCUSAURUS_CODE_TABS-->
## Enabling plugins on Android / iOS ## Enabling plugins
Finally, you need to add plugins to your Flipper client. Above we have only added the Layout Inspector plugin to get you started. See [Network Plugin](setup/network-plugin.md) and [Layout Inspector Plugin](setup/layout-plugin.md) for information on how to add them, and also enable Litho or ComponentKit support. You can check the sample apps in the [GitHub repo](https://github.com/facebook/flipper) for examples of integrating other plugins. Finally, you need to add plugins to your Flipper client. Above, we have only added the Layout Inspector plugin to get you started. See [Network Plugin](setup/network-plugin.md) and [Layout Inspector Plugin](setup/layout-plugin.md) for information on how to add them, and also enable Litho or ComponentKit support. You can check the sample apps in the [GitHub repo](https://github.com/facebook/flipper) for examples of integrating other plugins.
## Setup your React Native app
<div class="warning">
This tutorial is for React Native applications using version **0.62.0**, please refer to the following if you are using a different version:
* [Flipper on RN < 0.61.5 tutorial](https://github.com/facebook/flipper/blob/da25241f7fbb06dffd913958559044d758c54fb8/docs/getting-started.md#setup-your-react-native-app)
* [Flipper on RN 0.61.5 - 0.62 tutorial](https://github.com/facebook/flipper/blob/4297b3061f14ceca4d184aa3eebd0731b5bf20f5/docs/getting-started.md#setup-your-react-native-app)
</div>
After generating your project with `npx react-native init`, the Flipper integration is setup out-of-the-box for debug builds:
* For Android, start the Flipper Desktop application, and start your project using `yarn android`. Your application should appear in Flipper.
* For iOS, run `pod install` once in the `ios` directory of your project. After that, run `yarn ios` and start Flipper. Your application should show up in Flipper.
By default, the following plugins will be available:
* Layout Inspector
* Network
* Databases
* Images
* Shared Preferences
* Crash Reporter
* React DevTools
* Metro Logs
Additional plugins might be installed through NPM, please follow the instructions as provided by the plugin authors.
To create your own plugins and integrate with Flipper using JavaScript, check out our [writing plugins for React Native](tutorial/react-native) tutorial!
If you ever need to update the Flipper SDKs used in your project, the versions can be bumped in the `ios/Podfile` and `android/gradle.properties` files of your project.
<div class="warning">
For Android, Flipper works with both emulators and physical devices connected through USB. However on iOS, we don't support physical devices yet.
</div>
## Having trouble? ## Having trouble?
See the [troubleshooting page](troubleshooting.html) for help with known problems. See the [troubleshooting page](troubleshooting.html) for help with known problems.
<div class="warning">
On iOS, we currently do not support connecting to physical devices.
</div>

37
docs/getting-started/react-native.md Normal file
View File

@@ -0,0 +1,37 @@
---
id: react-native
title: Set up your React Native App
sidebar_label: React Native
---
<div class="warning">
This tutorial is for React Native applications using version **0.62.0**, please refer to the following if you are using a different version:
* [Flipper on RN < 0.61.5 tutorial](https://github.com/facebook/flipper/blob/da25241f7fbb06dffd913958559044d758c54fb8/docs/getting-started.md#setup-your-react-native-app)
* [Flipper on RN 0.61.5 - 0.62 tutorial](https://github.com/facebook/flipper/blob/4297b3061f14ceca4d184aa3eebd0731b5bf20f5/docs/getting-started.md#setup-your-react-native-app)
</div>
After generating your project with `npx react-native init`, the Flipper integration is setup out-of-the-box for debug builds:
* For Android, start the Flipper Desktop application, and start your project using `yarn android`. Your application should appear in Flipper.
* For iOS, run `pod install` once in the `ios` directory of your project. After that, run `yarn ios` and start Flipper. Your application should show up in Flipper.
By default, the following plugins will be available:
* Layout Inspector
* Network
* Databases
* Images
* Shared Preferences
* Crash Reporter
* React DevTools
* Metro Logs
Additional plugins might be installed through NPM, please follow the instructions as provided by the plugin authors.
To create your own plugins and integrate with Flipper using JavaScript, check out our [writing plugins for React Native](tutorial/react-native) tutorial!
If you ever need to update the Flipper SDKs used in your project, the versions can be bumped in the `ios/Podfile` and `android/gradle.properties` files of your project.

8
scripts/bump/bump.hs
View File

@@ -28,8 +28,8 @@ import qualified Control.Foldl as F
releaseReplacements :: [(FilePath, Pattern Version)] releaseReplacements :: [(FilePath, Pattern Version)]
releaseReplacements = releaseReplacements =
[("gradle.properties", "VERSION_NAME=" *> anyVersion) [("gradle.properties", "VERSION_NAME=" *> anyVersion)
,("docs/getting-started.md", spaces >> "debugImplementation 'com.facebook.flipper:flipper:" *> releaseVersion <* "'") ,("docs/getting-started/android-native.md", spaces >> "debugImplementation 'com.facebook.flipper:flipper:" *> releaseVersion <* "'")
,("docs/getting-started.md", spaces >> "releaseImplementation 'com.facebook.flipper:flipper-noop:" *> releaseVersion <* "'") ,("docs/getting-started/android-native.md", spaces >> "releaseImplementation 'com.facebook.flipper:flipper-noop:" *> releaseVersion <* "'")
,("docs/setup/leak-canary-plugin.md", spaces >> "debugImplementation 'com.facebook.flipper:flipper-leakcanary-plugin:" *> releaseVersion <* "'") ,("docs/setup/leak-canary-plugin.md", spaces >> "debugImplementation 'com.facebook.flipper:flipper-leakcanary-plugin:" *> releaseVersion <* "'")
,("docs/setup/layout-plugin.md", spaces >> "debugImplementation 'com.facebook.flipper:flipper-litho-plugin:" *> releaseVersion <* "'") ,("docs/setup/layout-plugin.md", spaces >> "debugImplementation 'com.facebook.flipper:flipper-litho-plugin:" *> releaseVersion <* "'")
,("docs/setup/network-plugin.md", spaces >> "debugImplementation 'com.facebook.flipper:flipper-network-plugin:" *> releaseVersion <* "'") ,("docs/setup/network-plugin.md", spaces >> "debugImplementation 'com.facebook.flipper:flipper-network-plugin:" *> releaseVersion <* "'")
@@ -39,8 +39,8 @@ releaseReplacements =
snapshotReplacements :: [(FilePath, Pattern Version)] snapshotReplacements :: [(FilePath, Pattern Version)]
snapshotReplacements = snapshotReplacements =
[("gradle.properties", "VERSION_NAME=" *> anyVersion) [("gradle.properties", "VERSION_NAME=" *> anyVersion)
,("docs/getting-started.md", spaces >> "debugImplementation 'com.facebook.flipper:flipper:" *> snapshotVersion <* "'") ,("docs/getting-started/android-native.md", spaces >> "debugImplementation 'com.facebook.flipper:flipper:" *> snapshotVersion <* "'")
,("docs/getting-started.md", spaces >> "releaseImplementation 'com.facebook.flipper:flipper-noop:" *> snapshotVersion <* "'") ,("docs/getting-started/android-native.md", spaces >> "releaseImplementation 'com.facebook.flipper:flipper-noop:" *> snapshotVersion <* "'")
] ]
flipperPath :: FilePath -> FilePath flipperPath :: FilePath -> FilePath

20
website/i18n/en.json
View File

@@ -102,8 +102,20 @@
"features/shared-preferences-plugin": { "features/shared-preferences-plugin": {
"title": "Shared Preferences" "title": "Shared Preferences"
}, },
"getting-started": { "getting-started/android-native": {
"title": "Getting Started" "title": "Set up your Android app",
"sidebar_label": "Android"
},
"getting-started/index": {
"title": "Desktop App"
},
"getting-started/ios-native": {
"title": "Set up your iOS app",
"sidebar_label": "iOS"
},
"getting-started/react-native": {
"title": "Set up your React Native App",
"sidebar_label": "React Native"
}, },
"setup/crash-reporter-plugin": { "setup/crash-reporter-plugin": {
"title": "Crash Reporter Setup", "title": "Crash Reporter Setup",
@@ -185,9 +197,9 @@
}, },
"categories": { "categories": {
"Features": "Features", "Features": "Features",
"Using Flipper": "Using Flipper", "Getting Started": "Getting Started",
"Plugin Setup": "Plugin Setup", "Plugin Setup": "Plugin Setup",
"Advanced Usage": "Advanced Usage", "Advanced": "Advanced",
"Extending Flipper": "Extending Flipper", "Extending Flipper": "Extending Flipper",
"Tutorial": "Tutorial", "Tutorial": "Tutorial",
"Plugin Development": "Plugin Development", "Plugin Development": "Plugin Development",

22
website/sidebars.json
View File

@@ -17,7 +17,12 @@
] ]
}, },
"setup": { "setup": {
"Using Flipper": ["getting-started", "troubleshooting"], "Getting Started": [
"getting-started/index",
"getting-started/android-native",
"getting-started/ios-native",
"getting-started/react-native"
],
"Plugin Setup": [ "Plugin Setup": [
"setup/layout-plugin", "setup/layout-plugin",
"setup/navigation-plugin", "setup/navigation-plugin",
@@ -29,10 +34,16 @@
"setup/leak-canary-plugin", "setup/leak-canary-plugin",
"setup/crash-reporter-plugin" "setup/crash-reporter-plugin"
], ],
"Advanced Usage": ["custom-ports", "stetho"] "Advanced": [
"custom-ports",
"stetho",
"troubleshooting"
]
}, },
"extending": { "extending": {
"Extending Flipper": ["extending/index"], "Extending Flipper": [
"extending/index"
],
"Tutorial": [ "Tutorial": [
"tutorial/intro", "tutorial/intro",
"tutorial/ios", "tutorial/ios",
@@ -62,6 +73,9 @@
"extending/establishing-a-connection", "extending/establishing-a-connection",
"extending/supporting-layout" "extending/supporting-layout"
], ],
"Internals": ["extending/arch", "extending/layout-inspector"] "Internals": [
"extending/arch",
"extending/layout-inspector"
]
} }
} }

2
website/siteConfig.js
View File

@@ -17,7 +17,7 @@ const siteConfig = {
projectName: 'flipper', projectName: 'flipper',
headerLinks: [ headerLinks: [
{doc: 'features/index', label: 'Features'}, {doc: 'features/index', label: 'Features'},
{doc: 'getting-started', label: 'Setup'}, {doc: 'getting-started/index', label: 'Setup'},
{doc: 'extending/index', label: 'Extending'}, {doc: 'extending/index', label: 'Extending'},
{href: repoUrl, label: 'GitHub'}, {href: repoUrl, label: 'GitHub'},
], ],