Get codebase ready for actually supporting versioning.

utils/pub/entrypoint.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 /**
- * The "packages" directory for an application or library.
+ * Pub operates over a directed graph of dependencies that starts at a root
+ * "entrypoint" package. This is typically the package where the current

[nweiz, 2012/05/18 21:16:01]

I'd make it more explicit that an entrypoint could be an application or a
library.

[Bob Nystrom, 2012/05/18 22:13:04]

Done.

+ * working directory is located. An entrypoint knows the [root] package it is
+ * associated with and is responsible for building the "packages" directory

[nweiz, 2012/05/18 21:16:01]

s/building/managing/

[Bob Nystrom, 2012/05/18 22:13:04]

Done.

+ * for it.
  *
- * This directory contains symlinks to all packages used by an app. These links
+ * That directory contains symlinks to all packages used by an app. These links
  * point either to the [SystemCache] or to some other location on the local
  * filesystem.
  */
-class PackagesDir {
+class Entrypoint {
   /**
-   * The package containing this directory.
+   * The root package this entrypoint is associated with.
    */
-  final Package owner;
+  final Package root;
 
   /**
    * The system-wide cache which caches packages that need to be fetched over
    * the network.
    */
   final SystemCache cache;
 
   /**
    * Packages which have already been loaded into memory.
    */
   final Map<PackageId, Package> _loadedPackages;
 
   /**
    * Packages which are currently being asynchronously installed to the
    * directory.
    */
   final Map<PackageId, Future<Package>> _pendingInstalls;
 
-  PackagesDir(this.owner, this.cache)
+  Entrypoint(this.root, this.cache)
   : _loadedPackages  = new Map<PackageId, Package>(),
     _pendingInstalls = new Map<PackageId, Future<Package>>();
 
   /**
-   * Returns the path to the "packages" directory.
+   * The path to this "packages" directory.
    */
-  // TODO(rnystrom): Make this path configurable.

[nweiz, 2012/05/18 21:16:01]

This TODO should probably come back now, right?

[Bob Nystrom, 2012/05/18 22:13:04]

Done.

-  String get path() => join(owner.dir, 'packages');
+  String get path() => join(root.dir, 'packages');
 
   /**
    * Ensures that the package identified by [id] is installed to the directory,
    * loads it, and returns it.
    *
    * If this completes successfully, the package is guaranteed to be importable
    * using the `package:` scheme.
    *
    * This will automatically install the package to the system-wide cache as
    * well if it requires network access to retrieve (specifically, if
@@ skipping 15 matching lines @@
       // If the package already exists in the directory, no need to re-install.
       if (exists) return new Future.immediate(null);
 
       if (id.source.shouldCache) {
         return cache.install(id).chain(
             (pkg) => createSymlink(pkg.dir, packageDir));
       } else {
         return id.source.install(id, packageDir).transform((found) {
           if (found) return null;
           // TODO(nweiz): More robust error-handling.
-          throw 'Package ${id.fullName} not found in source '
-            '"${id.source.name}".';
+          throw 'Package ${id.name} not found in source "${id.source.name}".';
         });
       }
     }).chain((_) => Package.load(packageDir, cache.sources));
 
     future.then((pkg) => _loadedPackages[id] = pkg);
     always(future, () => _pendingInstalls.remove(id));
     _pendingInstalls[id] = future;
 
     return future;
   }
 
   /**
-   * Installs the package identified by [id] and all its transitive
-   * dependencies.
+   * Installs all of the packages referred to by [packages] and their transitive
+   * dependencies. References are resolved using [entrypoint].
    */
-  Future<Package> installTransitively(PackageId id) {
+  Future installTransitively(Package entrypoint,

[nweiz, 2012/05/18 21:16:01]

Taking "Package entrypoint" here seems weird for a couple reasons. First, isn't
it always going to be identical to this.root? Second, "entrypoint" is a
confusing name for a package when it's also the name of this class.

Given that we're starting to think of installing dependencies as a holistic
action that involves resolving the whole dependency tree, it might make sense to
remove this method entirely and just move its contents into
#installDependencies.

[Bob Nystrom, 2012/05/18 22:13:04]

Yeah, that's just stale code from before this refactoring.
Ditto here.
Good call. Done.

+      List<PackageRef> packages) {
     var seen = new Set<PackageId>();
-    Future<Package> helper(id) {
-      if (seen.contains(id)) return new Future.immediate(null);
-      seen.add(id);
 
-      return install(id).chain((package) {
-        return Futures.wait(package.dependencies.map(helper)).
-          transform((_) => package);
-      });
+    Future helper(List<PackageRef> packages) {
+      return Futures.wait(packages.map((ref) {
+        return entrypoint.resolve(ref).chain((id) {
+          if (seen.contains(id)) return new Future.immediate(null);
+          seen.add(id);
+
+          return install(id).chain((package) {
+            return helper(package.dependencies);
+          });
+        });
+      }));
     }
 
-    return helper(id);
+    return helper(packages);
   }
 
   /**
-   * Installs all dependencies of [owner] to the "packages" directory. Returns a
-   * [Future] that completes when all dependencies are installed.
+   * Installs all dependencies of the [root] package to its "packages"
+   * directory. Returns a [Future] that completes when all dependencies are
+   * installed.
    */
   Future installDependencies() {
-    return Futures.wait(owner.dependencies.map(installTransitively)).
-      transform((_) => null);
+    return installTransitively(root, root.dependencies);
   }
 }