gn: Support build directories outside the source tree.

tools/gn/filesystem_utils.h

 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef TOOLS_GN_FILESYSTEM_UTILS_H_
 #define TOOLS_GN_FILESYSTEM_UTILS_H_
 
 #include <string>
 
 #include "base/files/file_path.h"
@@ skipping 98 matching lines @@
 //
 // The source_root should be a base::FilePath converted to UTF-8. On Windows,
 // it should begin with a "C:/" rather than being our SourceFile's style
 // ("/C:/"). The source root can end with a slash or not.
 //
 // Note that this does not attempt to normalize slashes in the output.
 bool MakeAbsolutePathRelativeIfPossible(const base::StringPiece& source_root,
                                         const base::StringPiece& path,
                                         std::string* dest);
 
-// Converts a directory to its inverse (e.g. "/foo/bar/" -> "../../").
-// This will be the empty string for the root directories ("/" and "//"), and
-// in all other cases, this is guaranteed to end in a slash.
-std::string InvertDir(const SourceDir& dir);
-
 // Collapses "." and sequential "/"s and evaluates "..".
 void NormalizePath(std::string* path);
 
 // Converts slashes to backslashes for Windows. Keeps the string unchanged
 // for other systems.
 void ConvertPathToSystem(std::string* path);
 
-// Takes a source-absolute path (must begin with "//") and makes it relative
-// to the given directory, which also must be source-absolute.
-std::string RebaseSourceAbsolutePath(const std::string& input,
-                                     const SourceDir& dest_dir);
+// Takes a path, |input|, and makes it relative to the given directory
+// |dest_dir|. Both inputs may be source-relative (e.g. begins with
+// with "//") or may be absolute.
+//
+// If supplied, the |source_root| parameter must be the absolute path

[brettw, 2014/11/05 19:59:49]

"must be" -> "is the". Can you explain here what happens if this is supplied?
The current comment gives no reason why you would bother specifying this.

[zeuthen, 2014/11/07 19:24:12]

Done.

+// to the source root and not end in a slash.
+std::string RebaseSourceAbsolutePath(
+    const std::string& input,
+    const SourceDir& dest_dir,
+    const base::StringPiece& source_root = base::StringPiece());
 
 // Returns the given directory with no terminating slash at the end, such that
 // appending a slash and more stuff will produce a valid path.
 //
 // If the directory refers to either the source or system root, we'll append
 // a "." so this remains valid.
 std::string DirectoryWithNoLastSlash(const SourceDir& dir);
 
 // Returns the "best" SourceDir representing the given path. If it's inside the
 // given source_root, a source-relative directory will be returned (e.g.
@@ skipping 37 matching lines @@
 
 SourceDir GetTargetOutputDir(const Target* target);
 OutputFile GetTargetOutputDirAsOutputFile(const Target* target);
 SourceDir GetTargetGenDir(const Target* target);
 OutputFile GetTargetGenDirAsOutputFile(const Target* target);
 
 SourceDir GetCurrentOutputDir(const Scope* scope);
 SourceDir GetCurrentGenDir(const Scope* scope);
 
 #endif  // TOOLS_GN_FILESYSTEM_UTILS_H_