Migrate GYP docs over from the wiki.

This CL migrates the GYP documentation over from the code.google.com
wiki:

Given that code.google.com is shutting down, and given that
the Gitiles browser that we use to view the source code supports
rendering markup (much like GitHub does), it seems reasonable to
migrate all of of the wiki content into the repository directly.

This CL is a first draft attempt at that. It was created by
using the code.google.com exporter to export to a temporary repo
on GitHub, and then the translated Markdown content was checked into
the GYP repo on chromium.googlesource.com. The translated content
was manually edited a bit to reformat things (text was wrapped,
tables of contents were added, lists and tables were adjusted)
but the content was unchanged from the wiki as of the date
of this CL.

R=bradnelson@google.com, bradnelson@chromium.org

Review URL: https://codereview.chromium.org/1047413002

README.md

@@ -0,0 +1,12 @@
+GYP can Generate Your Projects.
+
+Mailing list:  http://groups.google.com/group/gyp-developer
+
+* [User documentation](/docs/UserDocumentation.md)
+* [Input Format Reference](/docs/InputFormatReference.md)
+* [Language specification](/docs/LanguageSpecification.md)
+* [GYP Hacking](/docs/Hacking.md)
+* [GYP Testing](/docs/Testing.md)
+* [GYP vs. CMake](/docs/GypVsCMake.md)
+* [Source](/docs/Source.md)
+* [Buildbot](/docs/Buildbot.md)

docs/Buildbot.md

@@ -0,0 +1,9 @@
+# Buildbot
+
+Gyp's Buildbot status page can be found here:
+http://build.chromium.org/f/client/gyp/
+
+The code that implements Gyp's test waterfall is called "parasite" and is an
+experimental replacement for Buildbot's build master that uses trybots to run
+tests.  The code can be found here:
+http://src.chromium.org/viewvc/chrome/trunk/tools/parasite/

docs/GypVsCMake.md

@@ -0,0 +1,118 @@
+# GYP vs. CMake #
+
+GYP was originally created to generate native IDE project files (Visual Studio, Xcode) for building [Chromium](http://www.chromim.org).
+
+The functionality of GYP is very similar to the [CMake](http://www.cmake.org)
+build tool.  Bradley Nelson wrote up the following description of why the team
+created GYP instead of using CMake.  The text below is copied from
+http://www.mail-archive.com/webkit-dev@lists.webkit.org/msg11029.html
+
+```
+
+Re: [webkit-dev] CMake as a build system?
+Bradley Nelson
+Mon, 19 Apr 2010 22:38:30 -0700
+
+Here's the innards of an email with a laundry list of stuff I came up with a
+while back on the gyp-developers list in response to Mike Craddick regarding
+what motivated gyp's development, since we were aware of cmake at the time
+(we'd even started a speculative port):
+
+
+I did an exploratory port of portions of Chromium to cmake (I think I got as
+far as net, base, sandbox, and part of webkit).
+There were a number of motivations, not all of which would apply to other
+projects. Also, some of the design of gyp was informed by experience at
+Google with large projects built wholly from source, leading to features
+absent from cmake, but not strictly required for Chromium.
+
+1. Ability to incrementally transition on Windows. It took us about 6 months
+to switch fully to gyp. Previous attempts to move to scons had taken a long
+time and failed, due to the requirement to transition while in flight. For a
+substantial period of time, we had a hybrid of checked in vcproj and
+gyp generated
+vcproj. To this day we still have a good number of GUIDs pinned in the
+gyp files,
+because different parts of our release pipeline have leftover assumptions
+regarding manipulating the raw sln/vcprojs. This transition occurred from
+the bottom up, largely because modules like base were easier to convert, and
+had a lower churn rate. During early stages of the transition, the majority
+of the team wasn't even aware they were using gyp, as it integrated into
+their existing workflow, and only affected modules that had been converted.
+
+2. Generation of a more 'normal' vcproj file. Gyp attempts, particularly on
+Windows, to generate vcprojs which resemble hand generated projects. It
+doesn't generate any Makefile type projects, but instead produces msvs
+Custom Build Steps and Custom Build Rules. This makes the resulting projects
+easier to understand from the IDE and avoids parts of the IDE that simply
+don't function correctly if you use Makefile projects. Our early hope with
+gyp was to support the least common denominator of features present in each
+of the platform specific project file formats, rather than falling back on
+generated Makefiles/shell scripts to emulate some common abstraction. CMake by
+comparison makes a good faith attempt to use native project features, but
+falls back on generated scripts in order to preserve the same semantics on
+each platforms.
+
+3. Abstraction on the level of project settings, rather than command line
+flags. In gyp's syntax you can add nearly any option present in a hand
+generated xcode/vcproj file. This allows you to use abstractions built into
+the IDEs rather than reverse engineering them possibly incorrectly for
+things like: manifest generation, precompiled headers, bundle generation.
+When somebody wants to use a particular menu option from msvs, I'm able to
+do a web search on the name of the setting from the IDE and provide them
+with a gyp stanza that does the equivalent. In many cases, not all project
+file constructs correspond to command line flags.
+
+4. Strong notion of module public/private interface. Gyp allows targets to
+publish a set of direct_dependent_settings, specifying things like
+include_dirs, defines, platforms specific settings, etc. This means that
+when module A depends on module B, it automatically acquires the right build
+settings without module A being filled with assumptions/knowledge of exactly
+how module B is built. Additionally, all of the transitive dependencies of
+module B are pulled in. This avoids their being a single top level view of
+the project, rather each gyp file expresses knowledge about its immediate
+neighbors. This keep local knowledge local. CMake effectively has a large
+shared global namespace.
+
+5. Cross platform generation. CMake is not able to generate all project
+files on all platforms. For example xcode projects cannot be generated from
+windows (cmake uses mac specific libraries to do project generation). This
+means that for instance generating a tarball containing pregenerated
+projects for all platforms is hard with Cmake (requires distribution to
+several machine types).
+
+6. Gyp has rudimentary cross compile support. Currently we've added enough
+functionality to gyp to support x86 -> arm cross compiles. Last I checked
+this functionality wasn't present in cmake. (This occurred later).
+
+
+That being said there are a number of drawbacks currently to gyp:
+
+1. Because platform specific settings are expressed at the project file
+level (rather than the command line level). Settings which might otherwise
+be shared in common between platforms (flags to gcc on mac/linux), end up
+being repeated twice. Though in fairness there is actually less sharing here
+than you'd think. include_dirs and defines actually represent 90% of what
+can be typically shared.
+
+2. CMake may be more mature, having been applied to a broader range of
+projects. There a number of 'tool modules' for cmake, which are shared in a
+common community.
+
+3. gyp currently makes some nasty assumptions about the availability of
+chromium's hermetic copy of cygwin on windows. This causes you to either
+have to special case a number of rules, or swallow this copy of cygwin as a
+build time dependency.
+
+4. CMake includes a fairly readable imperative language. Currently Gyp has a
+somewhat poorly specified declarative language (variable expansion happens
+in sometimes weird and counter-intuitive ways). In fairness though, gyp assumes
+that external python scripts can be used as an escape hatch. Also gyp avoids
+a lot of the things you'd need imperative code for, by having a nice target
+settings publication mechanism.
+
+5. (Feature/drawback depending on personal preference). Gyp's syntax is
+DEEPLY nested. It suffers from all of Lisp's advantages and drawbacks.
+
+-BradN
+```

docs/Hacking.md

@@ -0,0 +1,102 @@
+# GYP Hacking
+
+Note that the instructions below assume that you have the Chromium
+[depot tools](http://dev.chromium.org/developers/how-tos/depottools)
+installed and configured.
+If you don't, you do not pass go, and you cannot collect your $200.
+
+## Getting the sources
+
+Best is to use git to hack on anything, you can set up a git clone of GYP
+as follows:
+
+```
+git clone https://chromium.googlesource.com/external/gyp.git
+cd gyp
+git svn init --prefix=origin/ -T trunk http://gyp.googlecode.com/svn/
+git config --replace-all svn-remote.svn.fetch trunk:refs/remotes/origin/master
+git svn fetch
+```
+
+At this point you should get a quick stream of output as git-svn rebuilds
+it's SVN version->SHA1 database:
+
+```
+Rebuilding .git/svn/refs/remotes/origin/master/...
+r1 = 880a7f243635258fa4938bb7ebf9b4d5f46e3e48
+r2 = 24a2a4ceedce0ae16d0a107d9898e4828775c633
+r3 = 41276136692399ac4bb84c6664d02384fcad70ad
+```
+
+If you get slow trickling output with a bunch of file names as such:
+
+```
+r1 = 880a7f243635258fa4938bb7ebf9b4d5f46e3e48 (refs/remotes/git-svn)
+        A       xc.py
+```
+
+then these instructions are out of date, and you're re-downloading
+the entire version history from SVN. Please update these instructions
+once you've figured out what's up.
+
+If you intend to commit your changes back to the GYP SVN repository,
+you need to configure git-svn's commit url.
+
+```
+git config svn-remote.svn.commiturl https://gyp.googlecode.com/svn/trunk
+```
+
+## Testing your change
+
+GYP has a suite of tests which you can run with the provided test driver
+to make sure your changes aren't breaking anything important.
+
+You run the test driver with e.g.
+
+```
+python gyptest.py
+python gyptest.py test/win  # Only run Windows-related tests.
+python gyptest.py -a -f ninja  # Only run ninja-related tests.
+```
+
+See [Testing](Testing) for more details on the test framework.
+
+Note that it can be handy to look at the project files output by the tests
+to diagnose problems. The easiest way to do that is by kindly asking the
+test driver to leave the temporary directories it creates in-place.
+This is done by setting the enviroment variable "PRESERVE", e.g.
+
+```
+set PRESERVE=all     # On Windows
+export PRESERVE=all  # On saner platforms.
+```
+
+## Reviewing your change
+
+All changes to GYP must be code reviewed before submission, GYP uses rietveld.
+
+Upload your change with:
+
+```
+git cl upload
+```
+
+## Submitting
+
+Once you're ready to submit, you can use the GYP try bots to test your change
+with e.g.
+
+```
+git try
+```
+
+Once the change has been approved (LGTMed) and passes trybots, you can submit
+it with:
+
+```
+git cl dcommit
+```
+
+To be allowed to submit, you will need committer rights in the project, and
+your password for the SVN server.  You can get that password here:
+https://code.google.com/hosting/settings