doc(compiler): ivy seperate compilation design document by chuckjaz · Pull Request #22480 · angular/angular

chuckjaz · 2018-02-27T18:26:16Z

PR Type

What kind of change does this PR introduce?

[x] Documentation content changes

Design document for how the ivy compiler will handle metadata for separate compilation.

Does this PR introduce a breaking change?

[ ] Yes
[x] No

mary-poppins · 2018-02-27T18:33:42Z

You can preview e25c865 at https://pr22480-e25c865.ngbuilds.io/.

mhevery · 2018-02-27T19:40:45Z

packages/compiler/design/separate_compilation.md

providers should be ngInjectorDef?
viewProviders should be ngComponentDef?

Yes. Will fix.

mary-poppins · 2018-02-27T22:04:02Z

You can preview bc954a7 at https://pr22480-bc954a7.ngbuilds.io/.

trotyl · 2018-02-28T01:53:10Z

packages/compiler/design/separate_compilation.md

+@NgModule({
+  imports: [CommonModule, UtilityModule],
+  declarations: [MyComponent, MyDirective, MyComponent],
+  exports: [MyComponent, MyDirective, MyComponent, UtilityModule],


Duplicate MyComponent?

trotyl · 2018-02-28T01:55:48Z

packages/compiler/design/separate_compilation.md

+dependencies change, their factories would be invalid preventing them from
+version ranges in their dependencies. To support producing factories from
+compiled source (already translated by TypeScript into JavaScript)
+libraries include metadata that describe the content of the the Angular


Double the?

trotyl · 2018-02-28T01:58:16Z

packages/compiler/design/separate_compilation.md

+the decorator can be thought of as parameters to a class transformer that
+transforms the information in the decorator into the corresponding
+definition. An `@Component` decorator transforms the class by adding
+an `ngComponentDef` static variable, `@Directive` adds `ngDirectiveDef`,


static property instead of static variable?

trotyl · 2018-02-28T01:59:59Z

packages/compiler/design/separate_compilation.md

+## Information needed
+
+The information available across compilations in Angular 5 is represented in
+the  compiler by a summary description. For example, components and directive


components and directive -> components and directives? Both plural?

trotyl · 2018-02-28T02:03:39Z

packages/compiler/design/separate_compilation.md

+The only pieces of information that are not generated into the definition are
+the directive selector and the pipe name as they go into the module scope.
+
+The information needed to build a `ngModuleScope` needs to be communicated


a -> an?

trotyl · 2018-02-28T02:08:09Z

packages/compiler/design/separate_compilation.md

+### Angular 5
+
+Angular 5 uses `.metadata.json` files to store information that is directly
+inferred form the `.ts` files and include value information that is not


form -> from?

trotyl · 2018-02-28T02:11:04Z

packages/compiler/design/separate_compilation.md

+types are included in `.d.ts` files and might not include the exports necessary
+for values, the metadata includes export clauses from the `.ts` file.
+
+When a module is flattened into a FESM (Flat EcmaScript Module), a flat


ECMAScript as per #22316 (comment)?

trotyl · 2018-02-28T02:22:01Z

packages/compiler/design/separate_compilation.md

+```ts
+@Component({
+  selector: 'my-comp',
+  template: `<h1>Hello, {{name}}!`


missing </h1>?

Ouch. The compiler in my head is broken.

vicb · 2018-02-28T07:14:50Z

packages/compiler/design/separate_compilation.md

+the metadata necessary to generate the factories, they cannot contain, 
+themselves, the generated factories. This is because, if any of there
+dependencies change, their factories would be invalid preventing them from
+version ranges in their dependencies. To support producing factories from


ranges or changes ?

ranges. You would be required to specify exact versions as you could not tolerate even a point release change.

vicb · 2018-02-28T07:15:07Z

packages/compiler/design/separate_compilation.md

+### Angular Ivy
+
+In Ivy, the runtime is crafted in a way that allows for separate compilation
+by preforming at runtime much of what was previously pre-calculated by


preforming -> performing ?

vicb · 2018-02-28T07:17:25Z

packages/compiler/design/separate_compilation.md

+compiler. This allows the definition of components to change without
+requiring modules and components that depend on them being recompiled.
+
+The mental model of Ivy is that the decorator is the compiler. That is


"the decorator is the compiler" I am not a fan of this terminology. Doesn't it bring some confusion ?

It is the model we want to eventually have. That is, we want the decorator to be a class transformer. A transformer is a compiler.

It is the model we want to eventually have. That is, we want the decorator to be a class transformer. A transformer is a compiler.

I understand the concept. However IMO saying "the decorator is the compiler" without further explanation is confusing. I also find "class transformer" confusing here wrt to TS transformer.

I am not saying that anything is wrong only that it deserves some more explanation.

vicb · 2018-02-28T07:20:12Z

packages/compiler/design/separate_compilation.md

+interpreting the template, the compiler needs to know the selector defined for
+each component, directive and pipe that are in scope of the template. The
+purpose of this document is to define what information is needed by the
+compiler that is not provided by the decorator, is serialized, discovered and


ie "what information is needed by the compiler that is not provided by the decorator" -> you just told me that the compiler is the decorator

Also I am not sure to understand this sentence

vicb · 2018-02-28T07:30:20Z

packages/compiler/design/separate_compilation.md

+*my.component.ts*
+```js
+export class MyComponent {
+  name: string;


static ngSelector ?

No. We don't emit the ngSelector, it is only present in the metadata. Or, you can think of it as, we pre-remove it. "Manual considerations" below describes how to get build optimizer to remove it for you if you define the component manually.

vicb · 2018-02-28T07:31:45Z

packages/compiler/design/separate_compilation.md

+  constructor() {
+    this.dirId = 'some id';
+  }
+  static ngDirectiveDef = defineDirective({...});


+ngSelector

skreborn · 2018-02-28T08:20:14Z

packages/compiler/design/separate_compilation.md

+### Angular 5
+
+In 5.0 and prior versions of Angular the compiler performs whole program
+analysis and generates template and injector definitions that are use


I believe this was meant to read "injector definitions that are using this global knowledge".

skreborn · 2018-02-28T08:21:19Z

packages/compiler/design/separate_compilation.md

+Separate component and module compilation is supported only at the module
+definition level and only from source. That is, npm packages must contain
+the metadata necessary to generate the factories, they cannot contain, 
+themselves, the generated factories. This is because, if any of there


Once again, "if any of their dependencies change".

skreborn · 2018-02-28T08:38:41Z

packages/compiler/design/separate_compilation.md

+The metadata for a module is transformed by:
+
+1. Remove the `@NgModule` directive.
+2. Add  `"ngPipeDef": {}` static field.


Did you mean ngInjectorDef?

Cut/paste error.

mary-poppins · 2018-02-28T17:20:49Z

You can preview 8e79432 at https://pr22480-8e79432.ngbuilds.io/.

vicb · 2018-02-28T17:41:20Z

packages/compiler/design/separate_compilation.md

+```js
+export class MyComponent {
+  name: string;
+  static ngComponentDef = defineComponent({...});


wrt to my comment about ngSelector I understand what you mean. But how does it fit with l138.
Needs more explanation ?

This document only describes the metadata so 138 describing the transforms to the metadata, not the source. The source is only included here for illustration.

vicb · 2018-02-28T17:42:02Z

packages/compiler/design/separate_compilation.md

+export class MyPipe {
+  transform(...) ...
+  static ngPipeDef = definePipe({...});
+  static ngSelector = 'myPipe';


Why do we have ngSelector here ? (cf my comment about more explanation)

It shouldn't have been. Removed.

vicb · 2018-02-28T17:44:54Z

packages/compiler/design/separate_compilation.md

+
+The mental model of Ivy is that the decorator is the compiler. That is
+the decorator can be thought of as parameters to a class transformer that
+transforms the information in the decorator into the corresponding


"transforms" here is confusing wrt "class transformer".
May be rephrase to say that it transforms the class by generating definitions based on the decorator parameters ?

vicb · 2018-02-28T17:45:54Z

packages/compiler/design/separate_compilation.md

+interpreting the template, the compiler needs to know the selector defined for
+each component, directive and pipe that are in scope of the template. The
+purpose of this document is to define what information is needed by the
+compiler that is not provided by the decorator is serialized, discovered and


still does not understand this sentence ? "by the decorator is serialized"

mary-poppins · 2018-02-28T17:46:13Z

You can preview 9a16b64 at https://pr22480-9a16b64.ngbuilds.io/.

vicb · 2018-02-28T17:47:09Z

packages/compiler/design/separate_compilation.md

+
+### `CompileDirectiveSummary`
+
+| field               | ivy                   |


find better description for those headers ? (field and ivy)

vicb · 2018-02-28T17:50:54Z

packages/compiler/design/separate_compilation.md

+understood by the compiler.
+
+Unfortunately, however, manually generated module contain references to
+classes that might not be necessary at runtime. Manually or third-party


Manually or third-party ...

I would rephrase this

Something like:

"Manually or third-party components can get the same [...] by removing the the ngSelector and ngModuleScope properties. When using the build optimizer (add link) this can be achieved by ..."

This would imply that could just not have it which is exactly the opposite think I am trying to convey.

vicb · 2018-02-28T17:52:32Z

packages/compiler/design/separate_compilation.md

+
+## Background
+
+### Angular 5


"Angular 5" -> "Render2" ? May be a quick description of what those terms means in this background section would be great.

vicb · 2018-02-28T17:53:24Z

packages/compiler/design/separate_compilation.md

+### Application output
+
+The output of the ivy compiler only optionally generates the factories
+generated by the Render2 style output of Angular 5.0. In Ivy, the information


use "ivy" or "Ivy" consistently

vicb · 2018-02-28T17:53:52Z

packages/compiler/design/separate_compilation.md

+
+The output of the ivy compiler only optionally generates the factories
+generated by the Render2 style output of Angular 5.0. In Ivy, the information
+that was generated in factories is now generated in Angular a definition that


"in Angular a definition" typo

vicb · 2018-02-28T18:04:01Z

packages/compiler/design/separate_compilation.md

+
+##### example - ivy package
+
+Ivy packages are not supported in Angular 6.0 as they are not recommended as


typo "as in"

vicb · 2018-02-28T18:06:41Z

Very nice updates !
_{Could you please use fixup commits to push the updates to the PR}

mary-poppins · 2018-02-28T18:23:19Z

You can preview eb93dce at https://pr22480-eb93dce.ngbuilds.io/.

mary-poppins · 2018-02-28T18:39:36Z

You can preview 78edab8 at https://pr22480-78edab8.ngbuilds.io/.

mary-poppins · 2018-02-28T18:49:21Z

You can preview 39f67a3 at https://pr22480-39f67a3.ngbuilds.io/.

mhevery · 2018-02-28T19:14:38Z

packages/compiler/design/separate_compilation.md

+The purpose of the "package" target is to produce a library package that will
+be an entry point for an npm package. Each entry point should be separately
+compiled using a "package" target. Note that this makes explicit the limitation
+that a module from a package cannot be directly lazily loaded. It must be


maybe add , because theres is nothing which will trigger the generation of the factory files

mary-poppins · 2018-02-28T19:36:12Z

You can preview 8dcdb91 at https://pr22480-8dcdb91.ngbuilds.io/.

mhevery · 2018-02-28T19:36:34Z

packages/compiler/design/separate_compilation.md

+
+#### `ivy_sources`
+
+The `ivy_sources` can be used as use to cause the ivy versions of files to be


This section is confusing. Could you add an example code, I think that would make it more clear.

mary-poppins · 2018-02-28T22:23:54Z

You can preview cfbbcf9 at https://pr22480-cfbbcf9.ngbuilds.io/.

Produces back-patch as described in the angular#22235 and referenced in angular#22480. This just contains the compiler implementations and the corresponding unit tests. Connecting the dots as described in angular#22480 will be in a follow on change.

Produces back-patch as described in the #22235 and referenced in #22480. This just contains the compiler implementations and the corresponding unit tests. Connecting the dots as described in #22480 will be in a follow on change. PR Close #22506

angular-automatic-lock-bot · 2019-09-13T09:22:11Z

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}

googlebot added the cla: yes label Feb 27, 2018

mhevery approved these changes Feb 27, 2018

View reviewed changes

docs(compiler): ivy separate compilation design document

bc954a7

chuckjaz force-pushed the r3_separate_compilation branch from e25c865 to bc954a7 Compare February 27, 2018 21:53

alexeagle added the area: core Issues related to the framework runtime label Feb 27, 2018

chuckjaz added the target: major This PR is targeted for the next major release label Feb 28, 2018

trotyl reviewed Feb 28, 2018

View reviewed changes

vicb reviewed Feb 28, 2018

View reviewed changes

skreborn reviewed Feb 28, 2018

View reviewed changes

fixup! docs(compiler): ivy separate compilation design document

8e79432

chuckjaz added 2 commits February 28, 2018 09:25

fixup! docs(compiler): ivy separate compilation design document

9a16b64

fixup! docs(compiler): ivy separate compilation design document

2f9d12a

vicb reviewed Feb 28, 2018

View reviewed changes

chuckjaz added 2 commits February 28, 2018 10:27

fixup! docs(compiler): ivy separate compilation design document

78edab8

fixup! docs(compiler): ivy separate compilation design document

39f67a3

fixup! docs(compiler): ivy separate compilation design document

8dcdb91

mhevery reviewed Feb 28, 2018

View reviewed changes

fixup! docs(compiler): ivy separate compilation design document

cfbbcf9

chuckjaz mentioned this pull request Feb 28, 2018

feat(ivy): produce Renderer2 back-patching and factories. #22506

Closed

chuckjaz added the action: merge The PR is ready for merge by the caretaker label Mar 1, 2018

alexeagle closed this in 8bb2f5c Mar 1, 2018

chuckjaz mentioned this pull request Mar 1, 2018

feat(compiler-cli): allow specifiying a "target" option. #22541

Closed

angular-automatic-lock-bot bot locked and limited conversation to collaborators Sep 13, 2019


		##### example - ivy package

		Ivy packages are not supported in Angular 6.0 as they are not recommended as


		#### `ivy_sources`

		The `ivy_sources` can be used as use to cause the ivy versions of files to be

Conversation

chuckjaz commented Feb 27, 2018

PR Type

Does this PR introduce a breaking change?

Uh oh!

mary-poppins commented Feb 27, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mary-poppins commented Feb 27, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mary-poppins commented Feb 28, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mary-poppins commented Feb 28, 2018

Uh oh!

Choose a reason for hiding this comment