[Breaking] Introduce Bundle Compiler

build/broccoli/build-packages.js

@@ -9,6 +9,7 @@ const UnwatchedDir = require('broccoli-source').UnwatchedDir;
 const transpileToES5 = require('./transpile-to-es5');
 const writePackageJSON = require('./write-package-json');
 const writeLicense = require('./write-license');
+const debugMacros = require('babel-plugin-debug-macros').default;
 
 const Project = require('../utils/project');
 const project = Project.from('packages');
@@ -136,7 +137,23 @@ function transpileCommonJS(pkgName, esVersion, tree) {
 
   let options = {
     annotation: `Transpile CommonJS - ${pkgName} - ${esVersion}`,
-    plugins: ['transform-es2015-modules-commonjs'],
+    plugins: [
+      [debugMacros, {
+        envFlags: {
+          source: '@glimmer/local-debug-flags',
+          flags: {
+            DEBUG: false
+          }
+        },
+        debugTools: {
+          source: '@glimmer/debug'
+        },
+        externalizeHelpers: {
+          module: true
+        }
+      }],
+      'transform-es2015-modules-commonjs'
+    ],
     sourceMaps: 'inline'
   };
 

guides/01-introduction.md

@@ -34,6 +34,99 @@ The code examples in this document are written in [TypeScript][typescript].
 [handlebars]: http://handlebarsjs.com
 [typescript]: http://www.typescriptlang.org
 
+## Architecture
+
+The key insight of Glimmer is that Handlebars is a declarative programming
+language for building and updating DOM. By structuring web UI around Handlebars
+templates as the central abstraction, we can use advanced techniques from
+programming languages and compilers to significantly boost the performance of
+web applications in practice.
+
+Because of this, Glimmer's architecture has more in common with compiler
+toolchains like clang/LLVM or javac/JVM than traditional JavaScript libraries.
+
+At a high level, Glimmer is made up of two parts:
+
+1. The compiler, which turns templates into optimized binary bytecode.
+2. The runtime, which evaluates that bytecode and translates its instructions into
+   things like creating DOM elements or instantiating JavaScript component classes.
+
+### Compiler
+
+The compiler is responsible for turning your program's Handlebars templates into
+Glimmer binary bytecode.
+
+Because Glimmer is an optimizing compiler, it must know about all of the
+templates in a program in order to understand how they work together. This is in
+contrast to transpilers like Babel, which can transform each file in isolation.
+
+As the compiler traverses your application and discovers templates, it parses
+each one and creates an _intermediate representation_ (IR). The IR is similar to
+the final bytecode program but contains symbolic references to external objects
+(other templates, helpers, etc.) that may not have been discovered yet.
+
+Once all of the templates have been parsed into IR, the compiler performs a
+final pass that resolves symbolic addresses and writes the final opcodes into a
+shared binary buffer. In native compiler terms, you can think of this as the
+"linking" step that produces the final executable.
+
+This binary executable is saved to disk as a `.gbx` file that can be served to a
+browser and evaluated with the runtime.
+
+But we're not quite done yet. The bytecode program will be evaluated in the
+browser where it needs to interoperate with JavaScript. For example, users
+implement their template helpers as JavaScript functions. In our compiled
+program, how do we know what function to call if the user types `{{formatDate
+user.createdAt}}`?
+
+During compilation, Glimmer will assign unique numeric identifiers to each
+referenced external object (like a helper or component). We call these
+identifiers _handles_, and they are how we refer to "live" JavaScript objects
+like functions in the binary bytecode.
+
+When evaluating Glimmer bytecode in the browser, instead of asking for the
+`"formatDate"` helper, the runtime might ask for the object with handle `4`.
+
+In order to satisfy this request, the compiler also produces a data structure
+called the _external module table_ that maps each handle to its associated
+JavaScript object.
+
+For example, imagine we compile a template that invokes two helpers, `formatDate` and
+`pluralize`. These helpers get assigned handles `0` and `1` respectively. In order to
+allow the runtime to turn those handles into the correct function object, the compiler
+might produce a map like this:
+
+```js
+// module-table.ts
+import formatDate from 'app/helpers/format-date';
+import pluralize from 'app/helpers/pluralize';
+
+export default [formatDate, pluralize];
+```
+
+With this data structure, we can easily implement a function that translates handles into
+the appropriate live object:
+
+```ts
+import moduleTable from './module-table';
+
+function resolveHandle<T>(handle: number): T {
+  return moduleTable[handle];
+}
+```
+
+You can think of the external module table as the bridge between Glimmer's
+bytecode and the JavaScript VM. We can compactly represent references to
+external objects in the bytecode using handles, and then rehydrate them later
+with minimal overhead.
+
+Now that we have our compiled bytecode and the module table, we're ready to run
+our app in the browser, or any other JavaScript environment, like Node.js.
+
+### Runtime
+
+TODO
+
 * * *
 
 [Next: Precompiler Overview »](./02-precompiler-overview.md)

package.json

@@ -29,6 +29,7 @@
     ]
   },
   "dependencies": {
+    "babel-plugin-debug-macros": "^0.1.11",
     "handlebars": "^4.0.6",
     "simple-dom": "^0.3.0",
     "simple-html-tokenizer": "^0.4.1"
@@ -68,4 +69,4 @@
     "tslint": "^4.0.2",
     "typescript": "^2.4.2"
   }
-}
+}

packages/@glimmer/bundle-compiler/index.ts

@@ -0,0 +1 @@
+export * from './lib/templates';