Add glossary, some renames

Reviewed By: jeanlauliac

Differential Revision: D5043919

fbshipit-source-id: ba6f47102747c0762a153cd860f8f61f090cf5d7

packages/metro-bundler/Glossary.md

@@ -0,0 +1,22 @@
+Glossary
+===
+
+Terminology commonly used in React Native Packager / Metro Bundler is explained
+here. This document is work in progress, please help completing it.
+
+## Build Root
+
+Configuration files (`rn-cli.config.js`) support configuring one or more roots
+that are watched for file changes during development. In the context of the
+integration with the `js_*` rule family in [Buck][], there is only a single root,
+the build root used by Buck.
+
+
+## Local Path
+
+A *local path* / `localPath` is the path to a file relative to a
+[*build root*](#build-root).
+
+
+
+[Buck]: http://buckbuild.com/

packages/metro-bundler/src/Bundler/index.js

@@ -456,7 +456,7 @@ class Bundler {
       log(createActionEndEntry(transformingFilesLogEntry));
       onResolutionResponse(response);
 
-      // get entry file complete path (`entryFile` is relative to roots)
+      // get entry file complete path (`entryFile` is a local path, i.e. relative to roots)
       let entryFilePath;
       if (response.dependencies.length > 1) { // skip HMR requests
         const numModuleSystemDependencies =
@@ -603,12 +603,12 @@ class Bundler {
         const placeHolder = {};
         dependencies.forEach(dep => {
           if (dep.isAsset()) {
-            const relPath = getPathRelativeToRoot(
+            const localPath = toLocalPath(
               this._projectRoots,
               dep.path
             );
             promises.push(
-              this._assetServer.getAssetData(relPath, platform)
+              this._assetServer.getAssetData(localPath, platform)
             );
             ret.push(placeHolder);
           } else {
@@ -688,8 +688,8 @@ class Bundler {
     assetPlugins: Array<string>,
     platform: ?string = null,
   ) {
-    const relPath = getPathRelativeToRoot(this._projectRoots, module.path);
-    var assetUrlPath = joinPath('/assets', pathDirname(relPath));
+    const localPath = toLocalPath(this._projectRoots, module.path);
+    var assetUrlPath = joinPath('/assets', pathDirname(localPath));
 
     // On Windows, change backslashes to slashes to get proper URL path from file path.
     if (pathSeparator === '\\') {
@@ -698,7 +698,7 @@ class Bundler {
 
     const isImage = isAssetTypeAnImage(extname(module.path).slice(1));
 
-    return this._assetServer.getAssetData(relPath, platform).then(assetData => {
+    return this._assetServer.getAssetData(localPath, platform).then(assetData => {
       return Promise.all([isImage ? sizeOf(assetData.files[0]) : null, assetData]);
     }).then(res => {
       const dimensions = res[0];
@@ -842,11 +842,11 @@ class Bundler {
 
 }
 
-function getPathRelativeToRoot(roots, absPath) {
+function toLocalPath(roots, absPath) {
   for (let i = 0; i < roots.length; i++) {
-    const relPath = relativePath(roots[i], absPath);
-    if (relPath[0] !== '.') {
-      return relPath;
+    const localPath = relativePath(roots[i], absPath);
+    if (localPath[0] !== '.') {
+      return localPath;
     }
   }
 

packages/metro-bundler/src/lib/GlobalTransformCache.js

@@ -348,9 +348,9 @@ class OptionsHasher {
    * This function is extra-conservative with how it hashes the transform
    * options. In particular:
    *
-   *     * we need to hash paths relative to the root, not the absolute paths,
-   *       otherwise everyone would have a different cache, defeating the
-   *       purpose of global cache;
+   *     * we need to hash paths as local paths, i.e. relative to the root, not
+   *       the absolute paths, otherwise everyone would have a different cache,
+   *       defeating the purpose of global cache;
    *     * we need to reject any additional field we do not know of, because
    *       they could contain absolute path, and we absolutely want to process
    *       these.
@@ -397,21 +397,21 @@ class OptionsHasher {
       +dev | +generateSourceMaps << 1 | +hot << 2 | +!!inlineRequires << 3,
     ]));
     hash.update(JSON.stringify(platform));
-    let relativeBlacklist = [];
+    let blacklistWithLocalPaths = [];
     if (typeof inlineRequires === 'object') {
-      relativeBlacklist = this.relativizeFilePaths(Object.keys(inlineRequires.blacklist));
+      blacklistWithLocalPaths = this.pathsToLocal(Object.keys(inlineRequires.blacklist));
     }
-    const relativeProjectRoot = this.relativizeFilePath(projectRoot);
-    const optionTuple = [relativeBlacklist, relativeProjectRoot];
+    const localProjectRoot = this.toLocalPath(projectRoot);
+    const optionTuple = [blacklistWithLocalPaths, localProjectRoot];
     hash.update(JSON.stringify(optionTuple));
     return hash;
   }
 
-  relativizeFilePaths(filePaths: Array<string>): Array<string> {
-    return filePaths.map(this.relativizeFilePath.bind(this));
+  pathsToLocal(filePaths: Array<string>): Array<string> {
+    return filePaths.map(this.toLocalPath, this);
   }
 
-  relativizeFilePath(filePath: string): string {
+  toLocalPath(filePath: string): string {
     return path.relative(this._rootPath, filePath);
   }
 }