From 92ec92a338b9445c841c1cdec2fcd9b06fac74b3 Mon Sep 17 00:00:00 2001
From: Tim van der Lippe <tvanderlippe@chromium.org>
Date: Fri, 20 Mar 2020 15:02:52 +0000
Subject: [PATCH] Add documentation for GN-Typescript integration

Now that we have a stable implementation of our GN-Typescript integration,
add a README with basic usage and implementation details of it.

R=aerotwist@chromium.org,jacktfranklin@chromium.org

Bug: 1011811
Change-Id: I25a11b3483d306ae359c4bf11ecc34fcbff8fd6e
Reviewed-on: https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/2112367
Reviewed-by: Paul Lewis <aerotwist@chromium.org>
Reviewed-by: Jack Franklin <jacktfranklin@chromium.org>
Commit-Queue: Tim van der Lippe <tvanderlippe@chromium.org>
---
 third_party/typescript/README.md | 94 ++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)
 create mode 100644 third_party/typescript/README.md

diff --git a/third_party/typescript/README.md b/third_party/typescript/README.md
new file mode 100644
index 0000000000..4c91790b97
--- /dev/null
+++ b/third_party/typescript/README.md
@@ -0,0 +1,94 @@
+# GN TypeScript integration
+
+To integrate [gn] with [TypeScript], this directory contains a `ts_library` action to compile TypeScript and JavaScript sources with the TypeScript compiler `tsc`.
+
+To use the action, import the [`typescript.gni`] file:
+
+```python
+import("../../third_party/typescript/typescript.gni")
+```
+
+After importing, you can now use the `ts_library` action to define a GN task that compiles with `tsc`:
+
+```python
+ts_library("my_typescript_library") {
+  sources = [
+    "foo.ts",
+  ]
+}
+
+ts_library("my_javascript_library") {
+  sources = [
+    "bar.js",
+  ]
+}
+
+ts_library("my_mixed_library") {
+  sources = [
+    "typescript.ts",
+    "javascript.js",
+  ]
+}
+```
+
+The sources will be compiled with `tsc` and generate corresponding output in the `gen` folder in the `out` directory.
+
+To depend on other `ts_libraries`, specify the `deps`:
+
+```python
+ts_library("my_user_library") {
+  sources = [
+    "dependent.ts",
+  ]
+
+  deps = [
+    ":my_mixed_library",
+  ]
+}
+```
+
+`deps` use the same notation as [GN `deps`].
+Therefore, `ninja` will parallelize compilation of `ts_library` dependencies.
+
+A `ts_library` either needs to specify `sources`, `deps` or both.
+
+For tests compiled with `ts_library`, set `testonly = true`:
+
+```python
+ts_library("my_test_library") {
+  testonly = true,
+  sources = [
+    "my_library_test.ts",
+  ]
+
+  deps = [
+    "../../../../front_end/my_library",
+  ]
+}
+```
+
+Compiling with `testonly = true` will include the type definitions for `Node`, `Chai` and `Mocha`.
+
+To instruct Ninja to execute the `ts_library` task, make sure that there is a dependency chain from `/BUILD.gn` (or `test/*/BUILD.gn`) to the `ts_library` in question.
+
+## Implementation details
+
+A `ts_library` task will generate a `tsconfig.json` based on `/tsconfig.base.json` and write it to disk in the `gen` directory.
+Ater that, it will instruct `tsc` to compile the project based on the `tsconfig.json`.
+
+All `deps` are desugared to [project references].
+`tsc` will not recursively compile dependencies, Ninja handles that.
+
+Since Ninja does not recompile unchanged actions, all `ts_library` actions generate corresponding `.d.ts` files which specify the public API's of the sources, as well as the `.tsbuildinfo` for efficient recompilation with `tsc`.
+
+There are several global `.d.ts` files added to every `ts_library`.
+The `GLOBAL_TYPESCRIPT_DEFINITION_FILES` list in `ts_library.py` contains the list of all definition files.
+These files must also be listed as `inputs` in `typescript.gni`.
+
+**Legacy:** For legacy reasons, all non-testonly outputs are also copied to `resources/inspector` in the `out` directory.
+
+[gn]: https://gn.googlesource.com/gn/+/master/docs/reference.md
+[TypeScript]: https://www.typescriptlang.org/
+[`typescript.gni`]: typescript.gni
+[GN `deps`]: https://gn.googlesource.com/gn/+/master/docs/reference.md#var_deps
+[project references]: https://www.typescriptlang.org/docs/handbook/project-references.html
\ No newline at end of file