doc/org.eclipse.xpand.doc/help/incrementalGeneration.html - m2t/org.eclipse.xpand - Git at Google

 <html>
 <head>
 <title>Incremental Generation</title>
 <link href="book.css" rel="stylesheet" type="text/css"/>
 <meta content="DocBook XSL Stylesheets V1.75.1" name="generator"/>
 <link rel="home" href="index.html" title="Xpand Documentation"/>
 <link rel="up" href="Reference.html" title="Part I. Reference"/>
 <link rel="prev" href="eclipse_integration_running_a_workflow.html" title="Running a workflow"/>
 <link rel="next" href="incrementalGeneration_usage.html" title="Using Incremental Generation"/>
 </head>
 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
 <h1 xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">Incremental Generation</h1>
 <div class="chapter" title="Incremental Generation">
 <div class="titlepage">
 <div>
 <div>
 <h2 class="title">
 <a name="incrementalGeneration"/>Incremental Generation</h2>
 </div>
 </div>
 </div>
 <div class="toc">
 <dl>
 <dt>
 <span class="section">
 <a href="incrementalGeneration.html#incrementalGeneration_background">Technical Background</a>
 </span>
 </dt>
 <dt>
 <span class="section">
 <a href="incrementalGeneration_usage.html">Using Incremental Generation</a>
 </span>
 </dt>
 <dt>
 <span class="section">
 <a href="incrementalGeneration_notes.html">Additional Notes</a>
 </span>
 </dt>
 </dl>
 </div>
 <p>
     As projects become larger, so typically do their models. However, the larger
     the models are, the longer the code generation process takes. In a mature
     project, a developer typically changes only a small part of a large model.
     Performing a full code generation process for the whole model slows down the
     development cycle considerably due to various factors:

     </p>
 <div class="itemizedlist">
 <ul class="itemizedlist" type="disc">
 <li class="listitem">
         The whole model must be traversed, and each statement in the Xpand
         templates must be executed. The larger the model is and the more Xpand
         templates you have, the higher the negative impact is.
       </li>
 <li class="listitem">
         All generated files are written to disk. The I/O operation itself is
         one major contributor to the overall elapsed time. What's more, files
         are typically post-processed by beautifiers, which is another time
         consuming operation. If you are working with protected regions, the
         impact is even more dramatic.
       </li>
 <li class="listitem">
         Since every file has a new timestamp after code generation, typically
         a compiler will pick up these new files and start compilation, which
         adds more CPU and I/O cycles to the process.
       </li>
 </ul>
 </div>
 <p>

     Considering that for a small change in the model only a fraction of the
     generated files actually do change their contents, performing a full
     generation is obviously a waste of time.
   </p>
 <p>
     Beginning with the Helios release train (Eclipse 3.6, Xpand 0.8), Xpand
     now ships with an incremental generation facility. This works very similar
     to the incremental Java compiler in Eclipse. It detects which parts of a
     model have changed since the last generation process. It then
     determines which files need to be generated due to that change and which
     are unaffected by it. Only the former are the regenerated, while the
     latter remain untouched.
   </p>
 <p>
     The following sections explain how this incremental generation feature
     works and how you can use it.
   </p>
 <div class="section" title="Technical Background">
 <div class="titlepage">
 <div>
 <div>
 <h2 class="title" style="clear: both">
 <a name="incrementalGeneration_background"/>Technical Background</h2>
 </div>
 </div>
 </div>
 <p>
       The key to incremental generation lies in knowing which element in a model
       was used to generate which file. This information can easily be computed
       during generation, by tracking which parts of the model are
       accessed in the context of any given
       <code class="code">«FILE»</code> statement. A callback for the
       Xpand generator does this job and builds up a so-called
       <span class="emphasis">
 <em>trace model</em>
 </span> on-the-fly.
     </p>
 <p>
       The second important information is the actual change that has occurred
       in a model. There are basically two ways to compute this. One is to
       attach a change listener when editing the model and capture the change
       as it happens. The other way is to keep a backup copy of the model and
       compare the old version with the current version to compute the change.
       See <a class="xref" href="incrementalGeneration_notes.html#incrementalGeneration_performance" title="Performance Considerations">the section called “Performance Considerations”</a>
       for pros and cons of each of the two ways. In either
       case, the result is a so-called <span class="emphasis">
 <em>diff model</em>
 </span>.
     </p>
 <p>
       When we know which parts of a model have changed, and we also know which
       files have been produced based upon these parts of the model, we can then
       skip the generation of all other files, thus performing incremental
       generation.
     </p>
 </div>
 </div>
 </body>
 </html>
	<html>
	<head>
	<title>Incremental Generation</title>
	<link href="book.css" rel="stylesheet" type="text/css"/>
	<meta content="DocBook XSL Stylesheets V1.75.1" name="generator"/>
	<link rel="home" href="index.html" title="Xpand Documentation"/>
	<link rel="up" href="Reference.html" title="Part I. Reference"/>
	<link rel="prev" href="eclipse_integration_running_a_workflow.html" title="Running a workflow"/>
	<link rel="next" href="incrementalGeneration_usage.html" title="Using Incremental Generation"/>
	</head>
	<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
	<h1 xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">Incremental Generation</h1>
	<div class="chapter" title="Incremental Generation">
	<div class="titlepage">
	<div>
	<div>
	<h2 class="title">
	<a name="incrementalGeneration"/>Incremental Generation</h2>
	</div>
	</div>
	</div>
	<div class="toc">
	<dl>
	<dt>
	<span class="section">
	<a href="incrementalGeneration.html#incrementalGeneration_background">Technical Background</a>
	</span>
	</dt>
	<dt>
	<span class="section">
	<a href="incrementalGeneration_usage.html">Using Incremental Generation</a>
	</span>
	</dt>
	<dt>
	<span class="section">
	<a href="incrementalGeneration_notes.html">Additional Notes</a>
	</span>
	</dt>
	</dl>
	</div>
	<p>
	As projects become larger, so typically do their models. However, the larger
	the models are, the longer the code generation process takes. In a mature
	project, a developer typically changes only a small part of a large model.
	Performing a full code generation process for the whole model slows down the
	development cycle considerably due to various factors:

	</p>
	<div class="itemizedlist">
	<ul class="itemizedlist" type="disc">
	<li class="listitem">
	The whole model must be traversed, and each statement in the Xpand
	templates must be executed. The larger the model is and the more Xpand
	templates you have, the higher the negative impact is.
	</li>
	<li class="listitem">
	All generated files are written to disk. The I/O operation itself is
	one major contributor to the overall elapsed time. What's more, files
	are typically post-processed by beautifiers, which is another time
	consuming operation. If you are working with protected regions, the
	impact is even more dramatic.
	</li>
	<li class="listitem">
	Since every file has a new timestamp after code generation, typically
	a compiler will pick up these new files and start compilation, which
	adds more CPU and I/O cycles to the process.
	</li>
	</ul>
	</div>
	<p>

	Considering that for a small change in the model only a fraction of the
	generated files actually do change their contents, performing a full
	generation is obviously a waste of time.
	</p>
	<p>
	Beginning with the Helios release train (Eclipse 3.6, Xpand 0.8), Xpand
	now ships with an incremental generation facility. This works very similar
	to the incremental Java compiler in Eclipse. It detects which parts of a
	model have changed since the last generation process. It then
	determines which files need to be generated due to that change and which
	are unaffected by it. Only the former are the regenerated, while the
	latter remain untouched.
	</p>
	<p>
	The following sections explain how this incremental generation feature
	works and how you can use it.
	</p>
	<div class="section" title="Technical Background">
	<div class="titlepage">
	<div>
	<div>
	<h2 class="title" style="clear: both">
	<a name="incrementalGeneration_background"/>Technical Background</h2>
	</div>
	</div>
	</div>
	<p>
	The key to incremental generation lies in knowing which element in a model
	was used to generate which file. This information can easily be computed
	during generation, by tracking which parts of the model are
	accessed in the context of any given
	<code class="code">«FILE»</code> statement. A callback for the
	Xpand generator does this job and builds up a so-called
	<span class="emphasis">
	<em>trace model</em>
	</span> on-the-fly.
	</p>
	<p>
	The second important information is the actual change that has occurred
	in a model. There are basically two ways to compute this. One is to
	attach a change listener when editing the model and capture the change
	as it happens. The other way is to keep a backup copy of the model and
	compare the old version with the current version to compute the change.
	See <a class="xref" href="incrementalGeneration_notes.html#incrementalGeneration_performance" title="Performance Considerations">the section called “Performance Considerations”</a>
	for pros and cons of each of the two ways. In either
	case, the result is a so-called <span class="emphasis">
	<em>diff model</em>
	</span>.
	</p>
	<p>
	When we know which parts of a model have changed, and we also know which
	files have been produced based upon these parts of the model, we can then
	skip the generation of all other files, thus performing incremental
	generation.
	</p>
	</div>
	</div>
	</body>
	</html>