New Mojom Parser: Serialization.

mojom/mojom_parser/generated/README.md

Index: mojom/mojom_parser/generated/README.md
diff --git a/mojom/mojom_parser/generated/README.md b/mojom/mojom_parser/generated/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..ec9d95de6f231b3f732f629f78d8c2c05b1c4b87
--- /dev/null
+++ b/mojom/mojom_parser/generated/README.md
@@ -0,0 +1,44 @@
+Generated  Files
+==================
+
+The intermediate representation passed from the Mojom parser (the frontend
+of the Mojom compiler) to the code generators (the backend of the Mojom
+Compiler) is a `MojomFileGraph` described in  mojom_types.mojom and
+mojom_files.mojom in mojo/public/interfaces/bindings. Thus the Mojom compiler
+uses Mojo serialization to serialize the intermediate representation.
+
+This situation potentially entails a circular dependency because it means that
+in  order to build the Mojom compiler it is necessary to use code that has been
+generated by the Mojom compiler. In order to break this circular dependency we
+check in the generated code needed by the compiler rather than generating it
+while building the compiler.
+
+This directory contains the checked-in generated Go code used by the frontend
+of the compiler:
+mojom_files/mojom_files.mojom.go and
+mojom_types/mojom_types.mojom.go.
+
+The backend of the Mojom compiler is  written in Python and the corresponding
+generated Python files may be found in
+mojo/public/tools/bindings/pylib/mojom/generate/generated/mojom_files_mojom.py
+and
+mojo/public/tools/bindings/pylib/mojom/generate/generated/mojom_types_mojom.py
+
+### Instructions for updating these files
+1) Make changes to mojom_types.mojom and mojom_files.mojom. This may be done
+either in the same patch as everything below or in its own initial patch.
+2) Compile these files to produce new generated files:
+ninja -C out/Debug mojo/public/interfaces/bindings.
+3) Copy the newly generated mojom_files.mojom.go and mojom_types.mojom.go
+into the appropriate locations in this directory.
+4) mojom_files.mojom.go needs to be manually patched in a minor way. In the
+import section at the top replace "mojo/public/interfaces/bindings/mojom_types"
+with "mojom/mojom_parser/generated/mojom_types".
+5) Update the Go code in the serialization module of the parser to compensate
+for the changes if necessary. (Not necessary if the changes in step 1 were
+backward compatible.)
+6) Perform the analog of steps 3, 4, 5 for the Python code in the backend of
+the compiler. See
+mojo/public/tools/bindings/pylib/mojom/generate/generated/README.md
+for instructions.
+7) Land a patch containing your changes from steps 3 through 6.