feat: add a command to download the Hermes Sampling Profiler to a local machine

CONTRIBUTING.md

@@ -25,6 +25,7 @@ This repository is split into two packages:
 _Note: you must use the `--watchFolders` flag with the `start` command when testing the CLI with `yarn link` like this. Otherwise Metro can't find the symlinked folder and this may result in errors such as `ReferenceError: SHA-1 for file ... is not computed`._
 
 ### Setup
+
 Because of a modular design of the CLI, we recommend developing using symbolic links to its packages. This way you can use it seamlessly in the tested project, as you'd use the locally installed CLI. Here's what you need to run in the terminal:
 
 #### yarn v1
@@ -33,10 +34,12 @@ Because of a modular design of the CLI, we recommend developing using symbolic l
 cd /path/to/cloned/cli/
 yarn link-packages
 ```
+
 And then:
+
 ```sh
 cd /my/new/react-native/project/
-yarn link "@react-native-community/cli-platform-ios" "@react-native-community/cli-platform-android" "@react-native-community/cli" "@react-native-community/cli-server-api" "@react-native-community/cli-types" "@react-native-community/cli-tools" "@react-native-community/cli-debugger-ui"
+yarn link "@react-native-community/cli-platform-ios" "@react-native-community/cli-platform-android" "@react-native-community/cli" "@react-native-community/cli-server-api" "@react-native-community/cli-types" "@react-native-community/cli-tools" "@react-native-community/cli-debugger-ui" "@react-native-community/cli-hermes"
 ```
 
 Once you're done with testing and you'd like to get back to regular setup, run `yarn unlink` instead of `yarn link` from above command. Then `yarn install --force`.
@@ -51,6 +54,7 @@ yarn link /path/to/cloned/cli/ --all
 When you'd like to revert to a regular setup, you will need to revert the changes made to the `resolutions` field of `package.json`.
 
 ### Running
+
 ```sh
 yarn react-native start --watchFolders /path/to/cloned/cli/
 yarn react-native run-android

docs/commands.md

@@ -17,6 +17,7 @@ React Native CLI comes with following commands:
 - [`uninstall`](#uninstall)
 - [`unlink`](#unlink)
 - [`upgrade`](#upgrade)
+- [`profile-hermes`](#profile-hermes)
 
 ### `bundle`
 
@@ -546,3 +547,48 @@ Upgrade your app's template files to the specified or latest npm version using [
 Using this command is a recommended way of upgrading relatively simple React Native apps with not too many native libraries linked. The more iOS and Android build files are modified, the higher chance for a conflicts. The command will guide you on how to continue upgrade process manually in case of failure.
 
 _Note: If you'd like to upgrade using this method from React Native version lower than 0.59.0, you may use a standalone version of this CLI: `npx @react-native-community/cli upgrade`._
+
+### `profile-hermes`
+
+Usage:
+
+```sh
+react-native profile-hermes [destinationDir] <flag>
+```
+
+Pull and convert a Hermes tracing profile to Chrome tracing profile, then store it in the directory <destinationDir> of the local machine.
+
+- `destinationDir` is optional, if provided, pull the file to that directory
+  > default: pull to the current React Native app root directory
+
+#### Options
+
+#### `--fileName [string]`
+
+File name of the profile to be downloaded, eg. sampling-profiler-trace8593107139682635366.cpuprofile.
+
+> default: pull the latest file
+
+#### `--raw`
+
+Pulls the original Hermes tracing profile without any transformation
+
+#### `--sourcemap-path [string]`
+
+The local path to your source map file if you generated it manually, ex. `/tmp/sourcemap.json`
+
+#### `--generate-sourcemap`
+
+Generate the JS bundle and source map in `os.tmpdir()`
+
+#### '--port [number]',
+
+The running metro server port number
+
+> default: 8081
+
+### Notes on source map
+
+This step is recommended in order for the source map to be generated:
+
+If you are planning on building a debug APK, that will run without the packager, by invoking `./gradlew assembleDebug` you can simply set `bundleInDebug: true` in your app/build.gradle file, inside the `project.ext.react` map.

packages/cli-hermes/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@react-native-community/cli-hermes",
+  "version": "4.11.0",
+  "license": "MIT",
+  "main": "build/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "build/index.d.ts",
+  "dependencies": {
+    "@react-native-community/cli-tools": "^4.11.0",
+    "@react-native-community/cli-platform-android": "^4.11.0",
+    "chalk": "^3.0.0",
+    "hermes-profile-transformer": "^0.0.6",
+    "ip": "^1.1.5"
+  },
+  "files": [
+    "build",
+    "!*.d.ts",
+    "!*.map"
+  ],
+  "devDependencies": {
+    "@react-native-community/cli-types": "^4.10.1",
+    "@types/ip": "^1.1.0"
+  }
+}

packages/cli-hermes/src/index.ts

@@ -0,0 +1,2 @@
+import profileHermes from './profileHermes/index';
+export default profileHermes;

packages/cli-hermes/src/profileHermes/downloadProfile.ts

@@ -0,0 +1,128 @@
+import {Config} from '@react-native-community/cli-types';
+import {execSync} from 'child_process';
+import {logger, CLIError} from '@react-native-community/cli-tools';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import transformer from 'hermes-profile-transformer';
+import {findSourcemap, generateSourcemap} from './sourcemapUtils';
+import {
+  getAndroidProject,
+  getPackageName,
+} from '@react-native-community/cli-platform-android';
+/**
+ * Get the last modified hermes profile
+ * @param packageName
+ */
+function getLatestFile(packageName: string): string {
+  try {
+    const file = execSync(`adb shell run-as ${packageName} ls cache/ -tp | grep -v /$ | egrep '\.cpuprofile' | head -1
+        `);
+    return file.toString().trim();
+  } catch (e) {
+    throw new Error(e);
+  }
+}
+
+function execSyncWithLog(command: string) {
+  logger.debug(`${command}`);
+  return execSync(command);
+}
+
+/**
+ * Pull and convert a Hermes tracing profile to Chrome tracing profile
+ * @param ctx
+ * @param dstPath
+ * @param fileName
+ * @param sourceMapPath
+ * @param raw
+ * @param generateSourceMap
+ */
+export async function downloadProfile(
+  ctx: Config,
+  dstPath: string,
+  filename?: string,
+  sourcemapPath?: string,
+  raw?: boolean,
+  shouldGenerateSourcemap?: boolean,
+  port?: string,
+) {
+  try {
+    const androidProject = getAndroidProject(ctx);
+    const packageName = getPackageName(androidProject);
+
+    // If file name is not specified, pull the latest file from device
+    const file = filename || (await getLatestFile(packageName));
+    if (!file) {
+      throw new CLIError(
+        'There is no file in the cache/ directory. Did you record a profile from the developer menu?',
+      );
+    }
+
+    logger.info(`File to be pulled: ${file}`);
+
+    // If destination path is not specified, pull to the current directory
+    dstPath = dstPath || ctx.root;
+
+    logger.debug('Internal commands run to pull the file:');
+
+    // Copy the file from device's data to sdcard, then pull the file to a temp directory
+    execSyncWithLog(`adb shell run-as ${packageName} cp cache/${file} /sdcard`);
+
+    // If --raw, pull the hermes profile to dstPath
+    if (raw) {
+      execSyncWithLog(`adb pull /sdcard/${file} ${dstPath}`);
+      logger.success(`Successfully pulled the file to ${dstPath}/${file}`);
+    }
+
+    // Else: transform the profile to Chrome format and pull it to dstPath
+    else {
+      const osTmpDir = os.tmpdir();
+      const tempFilePath = path.join(osTmpDir, file);
+
+      execSyncWithLog(`adb pull /sdcard/${file} ${tempFilePath}`);
+
+      // If path to source map is not given
+      if (!sourcemapPath) {
+        // Get or generate the source map
+        if (shouldGenerateSourcemap) {
+          sourcemapPath = await generateSourcemap(port);
+        } else {
+          sourcemapPath = await findSourcemap(ctx, port);
+        }
+
+        // Run without source map
+        if (!sourcemapPath) {
+          logger.warn(
+            'Cannot find source maps, running the transformer without it',
+          );
+          logger.info(
+            'Instructions on how to get source maps: set `bundleInDebug: true` in your app/build.gradle file, inside the `project.ext.react` map.',
+          );
+        }
+      }
+
+      // Run transformer tool to convert from Hermes to Chrome format
+      const events = await transformer(
+        tempFilePath,
+        sourcemapPath,
+        'index.bundle',
+      );
+
+      const transformedFilePath = `${dstPath}/${path.basename(
+        file,
+        '.cpuprofile',
+      )}-converted.json`;
+      fs.writeFileSync(
+        transformedFilePath,
+        JSON.stringify(events, undefined, 4),
+        'utf-8',
+      );
+      logger.success(
+        `Successfully converted to Chrome tracing format and pulled the file to ${transformedFilePath}`,
+      );
+    }
+  } catch (e) {
+    throw e;
+  }
+}

packages/cli-hermes/src/profileHermes/index.ts

@@ -0,0 +1,77 @@
+import {logger, CLIError} from '@react-native-community/cli-tools';
+import {Config} from '@react-native-community/cli-types';
+import {downloadProfile} from './downloadProfile';
+
+type Options = {
+  filename?: string;
+  raw?: boolean;
+  sourcemapPath?: string;
+  generateSourcemap?: boolean;
+  port?: string;
+};
+
+async function profileHermes(
+  [dstPath]: Array<string>,
+  ctx: Config,
+  options: Options,
+) {
+  try {
+    logger.info(
+      'Downloading a Hermes Sampling Profiler from your Android device...',
+    );
+    if (!options.filename) {
+      logger.info('No filename is provided, pulling latest file');
+    }
+    await downloadProfile(
+      ctx,
+      dstPath,
+      options.filename,
+      options.sourcemapPath,
+      options.raw,
+      options.generateSourcemap,
+      options.port,
+    );
+  } catch (err) {
+    throw err as CLIError;
+  }
+}
+
+export default {
+  name: 'profile-hermes [destinationDir]',
+  description:
+    'Pull and convert a Hermes tracing profile to Chrome tracing profile, then store it in the directory <destinationDir> of the local machine',
+  func: profileHermes,
+  options: [
+    {
+      name: '--filename [string]',
+      description:
+        'File name of the profile to be downloaded, eg. sampling-profiler-trace8593107139682635366.cpuprofile',
+    },
+    {
+      name: '--raw',
+      description:
+        'Pulls the original Hermes tracing profile without any transformation',
+    },
+    {
+      name: '--sourcemap-path [string]',
+      description:
+        'The local path to your source map file, eg. /tmp/sourcemap.json',
+    },
+    {
+      name: '--generate-sourcemap',
+      description: 'Generates the JS bundle and source map',
+    },
+    {
+      name: '--port [number]',
+      default: process.env.RCT_METRO_PORT || 8081,
+      parse: (val: number) => String(val),
+    },
+  ],
+  examples: [
+    {
+      desc:
+        'Download the Hermes Sampling Profiler to the directory <destinationDir> on the local machine',
+      cmd: 'profile-hermes /tmp',
+    },
+  ],
+};