Index: utils/pub/entrypoint.dart |
diff --git a/utils/pub/entrypoint.dart b/utils/pub/entrypoint.dart |
index 56007e0fe78dd90ab32c0a88af95cdaae972a4be..897af2286b1e1a96a36f7bbf2ad657e2fb1400af 100644 |
--- a/utils/pub/entrypoint.dart |
+++ b/utils/pub/entrypoint.dart |
@@ -14,39 +14,31 @@ import 'utils.dart'; |
import 'version.dart'; |
import 'version_solver.dart'; |
-/** |
- * Pub operates over a directed graph of dependencies that starts at a root |
- * "entrypoint" package. This is typically the package where the current |
- * working directory is located. An entrypoint knows the [root] package it is |
- * associated with and is responsible for managing the "packages" directory |
- * for it. |
- * |
- * 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. |
- * |
- * While entrypoints are typically applications, a pure library package may end |
- * up being used as an entrypoint. Also, a single package may be used as an |
- * entrypoint in one context but not in another. For example, a package that |
- * contains a reusable library may not be the entrypoint when used by an app, |
- * but may be the entrypoint when you're running its tests. |
- */ |
+/// Pub operates over a directed graph of dependencies that starts at a root |
+/// "entrypoint" package. This is typically the package where the current |
+/// working directory is located. An entrypoint knows the [root] package it is |
+/// associated with and is responsible for managing the "packages" directory |
+/// for it. |
+/// |
+/// 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. |
+/// |
+/// While entrypoints are typically applications, a pure library package may end |
+/// up being used as an entrypoint. Also, a single package may be used as an |
+/// entrypoint in one context but not in another. For example, a package that |
+/// contains a reusable library may not be the entrypoint when used by an app, |
+/// but may be the entrypoint when you're running its tests. |
class Entrypoint { |
- /** |
- * The root package this entrypoint is associated with. |
- */ |
+ /// The root package this entrypoint is associated with. |
final Package root; |
- /** |
- * The system-wide cache which caches packages that need to be fetched over |
- * the network. |
- */ |
+ /// The system-wide cache which caches packages that need to be fetched over |
+ /// the network. |
final SystemCache cache; |
- /** |
- * Packages which are either currently being asynchronously installed to the |
- * directory, or have already been installed. |
- */ |
+ /// Packages which are either currently being asynchronously installed to the |
+ /// directory, or have already been installed. |
final Map<PackageId, Future<PackageId>> _installs; |
Entrypoint(this.root, this.cache) |
@@ -58,25 +50,21 @@ class Entrypoint { |
new Entrypoint(package, cache)); |
} |
- /** |
- * The path to this "packages" directory. |
- */ |
// TODO(rnystrom): Make this path configurable. |
+ /// The path to this "packages" directory. |
String get path => join(root.dir, 'packages'); |
- /** |
- * Ensures that the package identified by [id] is installed to the directory. |
- * Returns the resolved [PackageId]. |
- * |
- * 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 |
- * `id.source.shouldCache` is true). |
- * |
- * See also [installDependencies]. |
- */ |
+ /// Ensures that the package identified by [id] is installed to the directory. |
+ /// Returns the resolved [PackageId]. |
+ /// |
+ /// 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 |
+ /// `id.source.shouldCache` is true). |
+ /// |
+ /// See also [installDependencies]. |
Future<PackageId> install(PackageId id) { |
var pendingOrCompleted = _installs[id]; |
if (pendingOrCompleted != null) return pendingOrCompleted; |
@@ -108,32 +96,26 @@ class Entrypoint { |
return future; |
} |
- /** |
- * Installs all dependencies of the [root] package to its "packages" |
- * directory, respecting the [LockFile] if present. Returns a [Future] that |
- * completes when all dependencies are installed. |
- */ |
+ /// Installs all dependencies of the [root] package to its "packages" |
+ /// directory, respecting the [LockFile] if present. Returns a [Future] that |
+ /// completes when all dependencies are installed. |
Future installDependencies() { |
return _loadLockFile() |
.chain((lockFile) => resolveVersions(cache.sources, root, lockFile)) |
.chain(_installDependencies); |
} |
- /** |
- * Installs the latest available versions of all dependencies of the [root] |
- * package to its "package" directory, writing a new [LockFile]. Returns a |
- * [Future] that completes when all dependencies are installed. |
- */ |
+ /// Installs the latest available versions of all dependencies of the [root] |
+ /// package to its "package" directory, writing a new [LockFile]. Returns a |
+ /// [Future] that completes when all dependencies are installed. |
Future updateAllDependencies() { |
return resolveVersions(cache.sources, root, new LockFile.empty()) |
.chain(_installDependencies); |
} |
- /** |
- * Installs the latest available versions of [dependencies], while leaving |
- * other dependencies as specified by the [LockFile] if possible. Returns a |
- * [Future] that completes when all dependencies are installed. |
- */ |
+ /// Installs the latest available versions of [dependencies], while leaving |
+ /// other dependencies as specified by the [LockFile] if possible. Returns a |
+ /// [Future] that completes when all dependencies are installed. |
Future updateDependencies(List<String> dependencies) { |
return _loadLockFile().chain((lockFile) { |
var versionSolver = new VersionSolver(cache.sources, root, lockFile); |
@@ -144,10 +126,8 @@ class Entrypoint { |
}).chain(_installDependencies); |
} |
- /** |
- * Removes the old packages directory, installs all dependencies listed in |
- * [packageVersions], and writes a [LockFile]. |
- */ |
+ /// Removes the old packages directory, installs all dependencies listed in |
+ /// [packageVersions], and writes a [LockFile]. |
Future _installDependencies(List<PackageId> packageVersions) { |
return cleanDir(path).chain((_) { |
return Futures.wait(packageVersions.map((id) { |
@@ -159,13 +139,11 @@ class Entrypoint { |
.chain(_linkSecondaryPackageDirs); |
} |
- /** |
- * Loads the list of concrete package versions from the `pubspec.lock`, if it |
- * exists. If it doesn't, this completes to an empty [LockFile]. |
- * |
- * If there's an error reading the `pubspec.lock` file, this will print a |
- * warning message and act as though the file doesn't exist. |
- */ |
+ /// Loads the list of concrete package versions from the `pubspec.lock`, if it |
+ /// exists. If it doesn't, this completes to an empty [LockFile]. |
+ /// |
+ /// If there's an error reading the `pubspec.lock` file, this will print a |
+ /// warning message and act as though the file doesn't exist. |
Future<LockFile> _loadLockFile() { |
var lockFilePath = join(root.dir, 'pubspec.lock'); |
@@ -181,9 +159,7 @@ class Entrypoint { |
}); |
} |
- /** |
- * Saves a list of concrete package versions to the `pubspec.lock` file. |
- */ |
+ /// Saves a list of concrete package versions to the `pubspec.lock` file. |
Future _saveLockFile(List<PackageId> packageIds) { |
var lockFile = new LockFile.empty(); |
for (var id in packageIds) { |
@@ -195,10 +171,8 @@ class Entrypoint { |
return writeTextFile(lockFilePath, lockFile.serialize()); |
} |
- /** |
- * Installs a self-referential symlink in the `packages` directory that will |
- * allow a package to import its own files using `package:`. |
- */ |
+ /// Installs a self-referential symlink in the `packages` directory that will |
+ /// allow a package to import its own files using `package:`. |
Future _installSelfReference(_) { |
var linkPath = join(path, root.name); |
return exists(linkPath).chain((exists) { |
@@ -210,11 +184,9 @@ class Entrypoint { |
}); |
} |
- /** |
- * If `bin/`, `test/`, or `example/` directories exist, symlink `packages/` |
- * into them so that their entrypoints can be run. Do the same for any |
- * subdirectories of `test/` and `example/`. |
- */ |
+ /// If `bin/`, `test/`, or `example/` directories exist, symlink `packages/` |
+ /// into them so that their entrypoints can be run. Do the same for any |
+ /// subdirectories of `test/` and `example/`. |
Future _linkSecondaryPackageDirs(_) { |
var binDir = join(root.dir, 'bin'); |
var exampleDir = join(root.dir, 'example'); |
@@ -230,10 +202,8 @@ class Entrypoint { |
.chain((_) => _linkSecondaryPackageDirsRecursively(webDir)); |
} |
- /** |
- * Creates a symlink to the `packages` directory in [dir] and all its |
- * subdirectories. |
- */ |
+ /// Creates a symlink to the `packages` directory in [dir] and all its |
+ /// subdirectories. |
Future _linkSecondaryPackageDirsRecursively(String dir) { |
return dirExists(dir).chain((exists) { |
if (!exists) return new Future.immediate(null); |
@@ -251,10 +221,8 @@ class Entrypoint { |
} |
// TODO(nweiz): roll this into [listDir] in io.dart once issue 4775 is fixed. |
- /** |
- * Recursively lists the contents of [dir], excluding hidden `.DS_Store` files |
- * and `package` files. |
- */ |
+ /// Recursively lists the contents of [dir], excluding hidden `.DS_Store` |
+ /// files and `package` files. |
Future<List<String>> _listDirWithoutPackages(dir) { |
return listDir(dir).chain((files) { |
return Futures.wait(files.map((file) { |
@@ -271,9 +239,7 @@ class Entrypoint { |
}).transform(flatten); |
} |
- /** |
- * Creates a symlink to the `packages` directory in [dir] if none exists. |
- */ |
+ /// Creates a symlink to the `packages` directory in [dir] if none exists. |
Future _linkSecondaryPackageDir(String dir) { |
var to = join(dir, 'packages'); |
return exists(to).chain((exists) { |