Difference between createEmitAndSemanticDiagnosticsBuilderProgram and createProgram

[craigphicks]

A typescript wiki on incremental compiling says this about createEmitAndSemanticDiagnosticsBuilderProgram

  // TypeScript can use several different program creation "strategies":
  //  * ts.createEmitAndSemanticDiagnosticsBuilderProgram,
  //  * ts.createSemanticDiagnosticsBuilderProgram
  //  * ts.createAbstractBuilder
  // The first two produce "builder programs". These use an incremental strategy
  // to only re-check and emit files whose contents may have changed, or whose
  // dependencies may have changes which may impact change the result of prior
  // type-check and emit.
  // The last uses an ordinary program which does a full type check after every
  // change.
  // Between `createEmitAndSemanticDiagnosticsBuilderProgram` and
  // `createSemanticDiagnosticsBuilderProgram`, the only difference is emit.
  // For pure type-checking scenarios, or when another tool/process handles emit,
  // using `createSemanticDiagnosticsBuilderProgram` may be more desirable.

To be honest, I can't see clearly what the difference is between using createProgram(...,oldProgram,...) and

" ... use an incremental strategy to only re-check and emit files whose contents may have changed, or whose dependencies may have changes which may impact change the result of prior type-check and emit."

because I thought that was what using createProgram(...,oldProgram,...) already did.

Can anybody clarify?

[nonara]

Regarding incremental compilation, I would refer you to the TS docs to understand what it's used for. (Place to start: https://www.typescriptlang.org/tsconfig#incremental)

Incremental compilation is very helpful in that it can save time, as it monitors modification times on files to only recompile what is necessary during compile time. To do that, there are some some slight differences in the compiler host.

Here is my simplistic answer with regard to the difference in the programs:

A Program instance is essentially meant to be used once. It does not watch for file changes and automatically update itself.

A Builder Program is capable of watching files and continuously rebuilding as files are changed. (Notably, however, each still ultimately calls createProgram)

More info here: https://github.com/microsoft/TypeScript-wiki/blob/master/Using-the-Compiler-API.md#writing-an-incremental-program-watcher

As for the different create... you mentioned, these just create an optimized builder program for what you're intending to use it for. The builder program is generally only used if you want to create your own watch compiler, which is very advanced and unlikely that most people will want to use it.

Hope that helps!

[craigphicks]

Thanks!