Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found

Target

Select target project
  • eclipsefdn/it/websites/eclipse.org
  • zhoufang/eclipse.org
  • zacharysabourin/eclipse.org
  • oliviergoulet/eclipse.org
  • pkriefrvi/eclipse.org
  • federica/eclipse.org
  • cfrayne/eclipse.org
  • mjahn0qp/eclipse.org
  • davidremon/eclipse.org
  • rosariarossini/eclipse.org
  • chrisguindon/eclipse.org
  • cguindon/eclipse.org
  • jharrisj1m/eclipse.org
  • heurtemattes/eclipse.org
  • sebastienheurtematte/eclipse.org
  • mbarbero/eclipse.org
  • tiagolucas/eclipse.org
  • flzara/eclipse.org
  • wbeaton/eclipse.org
  • gnugomez/eclipse.org
  • shillout001/eclipse.org
21 results
Show changes
Hide whitespace changes
Inline Side-by-side
Showing
with 1501 additions and 0 deletions
static/articles/Article-BranchingWithEclipseAndCVS/images/tip.gif 0 → 100644
View file @ 49b7b027
static/articles/Article-BranchingWithEclipseAndCVS/images/tip.gif

406 B

static/articles/Article-BranchingWithEclipseAndCVS/info.xml 0 → 100644
View file @ 49b7b027
<article>
<bug id="122438"/>
<project id="eclipse">
<release>3.2</release>
<release>3.3</release>
</project>
</article>
\ No newline at end of file
static/articles/Article-Branding/about.xml 0 → 100644
View file @ 49b7b027
<article link="branding-your-application.html">
<title>Branding Your Application</title>
<date>September 16, 2004</date>
<category>RCP</category>
<author>
<name>Andrew Eidsness</name>
<company>IBM</company>
</author>
<author>
<name>Pascal Rapicault</name>
<company>IBM</company>
</author>
<description>
In this article we look at how to create branding for your
Eclipse-based application. Branding is how you change the high
level visual elements of your product. This includes items such
as the splash screen, the about dialog, and the program
executable.
</description>
</article>
\ No newline at end of file
static/articles/Article-Branding/branding-your-application.html 0 → 100644
View file @ 49b7b027
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<title>Branding your application</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta name="Author" content="Andrew Eidsness and Pascal Rapicault">
<link rel="stylesheet" href="../default_style.css">
</head>
<body LINK="#0000ff" VLINK="#800080">
<div align="right">
<font face="Times New Roman, Times, serif" size="2">Copyright &copy; 2004
International Business Machines Corporation. All rights reserved</font>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr>
<td align="left" valign="top" colspan="2" bgcolor="#0080c0"><b><font face="Arial,Helvetica"><font color="#ffffff">Eclipse
Corner Article</font></font></b></td>
</tr>
</table>
</div>
<div align="left">
<h1><img src="images/idea.jpg" align="center" width="120" height="86"></h1>
</div>
<center>
<h1>Branding Your Application</h1>
</center>
<blockquote>
<b>Summary</b><br>
In this article we look at how to create branding for your Eclipse-based
application. Branding is how you change the high level visual elements of your
product. This includes items such as the splash screen, the about dialog, and
the program executable.
<p><b>By Andrew Eidsness and Pascal Rapicault, IBM OTI Labs</b><br>
<font size="-1">September 16, 2004</font></p>
</blockquote>
<hr width="100%">
<h2>Intended Audience</h2>
<p>You have completed the functionality of your RCP based application but are
unhappy because it still looks too much like a default Eclipse application. It
is time to &quot;brand your product,&quot; which consists of changing aspects
such as the icon used by the launcher, the splash screen, the window image, and
more. This article will help you to accomplish these tasks and will point you to
other documents of interest.</p>
<h2>Reading this article</h2>
<p>This article has been separated into three main sections:</p>
<ul>
<li><a href="#product_branding">Product branding</a></li>
<li><a href="#launcher_branding">Branding the launcher</a></li>
<li><a href="#optional_branding">Optional branding</a></li>
</ul>
<p>As you work through the steps you may notice the occasional <img src="images/TryIt.gif" width="61" height="13">
image. These indicate points at which you may want to test out the work you have
done thus far.</p>
<p>The steps in this document assume that you have access to the SDK build but
all of the changes we described can be applied to any RCP based application. In
the remaining sections we assume that you have a working knowledge of Eclipse
based development. In particular we assume that you know how to provide
translatable strings for your plug-in (see <a href="http://help.eclipse.org/help30/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/product_def_nl.htm">Locale
specific files</a>).</p>
<p>Make sure that you have installed the <a href="http://www.eclipse.org/downloads/index.php">RCP
Runtime Binary</a> before continuing. You should not consider branding or
productization unless you are also including your own plug-ins. In this article
we use the RCP Browser Example as the target product. To help follow along with
examples, you should download this plug-in from the <a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.ui.examples.rcp.browser/">Eclipse
repository</a>.</p>
<p>NOTE: This article is intended to be a guide to help you produce a release.
You need to ensure that you comply with any terms and conditions of the license
under which you received the platform runtime.</p>
<h2><a name="product_branding">Product branding</a></h2>
<p>The branding changes we'll described are those aspects related to the
appearance of your running application. These branding elements are supplied
with the <a href="http://help.eclipse.org/help30/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/extension-points/org_eclipse_core_runtime_products.html"><code>org.eclipse.core.runtime.product</code></a>
extension point. This controls (among other things) the application's title bar,
the window image, and the default application. We will describe parts of this
extension point here and will return to it in the <a href="#optional_branding">optional
branding</a> section.</p>
<h3>The product's title bar</h3>
<p><img name="Window's title bar" src="images/title.png" / width="400" height="52"></p>
<p>The product's title bar is controlled by the <code>name</code> attribute of
the product extension. Changing the browser's <code>plugin.xml</code> file as
highlighted below will replace the initial window title bar with your own
string.</p>
<blockquote>
<pre>&lt;extension
point=&quot;org.eclipse.core.runtime.products&quot;
id=&quot;product&quot;&gt;
&lt;product
name=<font style="background-color: yellow" color="#0000FF">&quot;Branded RCP Browser Example&quot;</font>
application=&quot;org.eclipse.ui.examples.rcp.browser.app&quot;&gt;
&lt;property ... </pre>
</blockquote>
<h3><b>The image the window system associates with the product</b></h3>
<p><img name="Window's title" src="images/windowImage.png" / width="400" height="52"></p>
<p>SWT allows a set of images to be associated with a shell with the expectation
that all images in the set will have the same appearance but be rendered at
different sizes. These images are provided to the SWT shell which is then able
to select the most appropriate one for each specific use. For example, on
Windows® the smaller image (16x16) will be used for the title and task bars
while the larger image (32x32) will appear in the Alt-Tab application switcher.</p>
<p>The comma-separated list that is set in the <i>windowImages</i> property
should have at least one image.</p>
Making the highlighted change to the <code>plugin.xml</code> file will change
the icons used by the product.
<blockquote>
<pre>&lt;extension ...
&lt;product ...
&lt;property
name=&quot;windowImages&quot;
value=<font style="background-color: yellow" color="#0000ff">&quot;icons/alt16.gif,icons/alt32.gif&quot;</font>/&gt;
&lt;property ... </pre>
</blockquote>
<h3><b>The name the window system associates with the product</b></h3>
<p>SWT allows an internal name to be associated with a shell. This name is
different from the one that appears in the shell's title bar -- its exact use
varies depending on the window system. For example, on X-Window based systems
such as motif this value is used to refer to the application in the .XDefaults
file.</p>
<p>The value of the <i>appName</i> property should be set to something that
clearly identifies your product. Its also a good idea to test your branding on a
platform (e.g., motif) that is known to use this value.</p>
<blockquote>
<pre>&lt;extension ...
&lt;product ...
&lt;property
name=&quot;appName&quot;
value=<font style="background-color: yellow" color="#0000ff">&quot;BrandedRCPBrowserExample&quot;</font>/&gt;
&lt;property ... </pre>
</blockquote>
<h3>Setting the&nbsp;product's default&nbsp;application</h3>
<p>The products extension is used to apply branding to your application but you
must also provide an <a href="http://help.eclipse.org/help30/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/extension-points/org_eclipse_core_runtime_applications.html">applications</a>
extension point. Among other thing this supplies the &quot;main&quot; to be run.
For example the Eclipse SDK has one brand but contains several applications
(e.g., the IDE, the ant runner, etc.) and for this specific case the IDE is the
default application.</p>
<p>You must designate a specific application as the default application to be
run when some branding is selected. This is accomplished by the <code>application</code>
attribute in your products extension.
<blockquote>
<pre>&lt;extension
point=&quot;org.eclipse.core.runtime.products&quot;
id=&quot;product&quot;&gt;
&lt;product
<font style="background-color: yellow" color="#0000ff">application=&quot;org.eclipse.ui.examples.rcp.browser.app&quot;</font>
...</pre>
</blockquote>
<h3><img src="images/TryIt.gif" width="61" height="13">&nbsp;Testing the
branding while self-hosting</h3>
<p>In the Eclipse IDE create a new runtime-workbench launch configuration,
choose the &quot;Run a product&quot; option, and select <code>org.eclipse.ui.examples.rcp.browser.product</code>
from the dropdown.
<p>By default the launch configuration loads all workspace and enabled external
plug-ins which may cause problems when running your application (since several
unneeded plug-ins will be included). Create a minimal set of plug-ins by
choosing the &quot;Plug-ins&quot; tab and selecting &quot;Choose plug-ins and
fragments to launch from the list&quot;. Click on &quot;Deselect All&quot; and
then choose the <code>org.eclipse.ui.examples.rcp.browser</code> plug-in.
Finally click on &quot;Add Required Plug-ins&quot; to compute the minimal set of
plug-ins required for your application.</p>
<p>The images referenced in this example are already in the <code>icons/</code>
directory of the browser plug-in so after making the changes described in this
section you are ready to click on &quot;Run&quot; to launch your application.
Look for the new window images and title.</p>
<h2><a name="launcher_branding">Branding the launcher</a></h2>
<p>The next step in developing your overall product brand is to change the
elements that appear while launching your application. This includes aspects
such as using your own splash screen and changing the icon used by the Eclipse
launcher.</p>
<p>These changes apply to the Eclipse launcher, which is not used in
self-hosting mode. That means that in order to observe these changes you will
need to have your RCP application installed on your system so that you can start
it directly. It also means that we will be changing your RCP application's <code>config.ini</code>
file (in the configuration area (<code>eclipse/configuration</code>)) rather
than any of its extension points.</p>
<h3>Make your product active</h3>
<p>If you haven't already done so then now is the time to edit the <code>config.ini</code>
file so that your branding is selected when your application is launched. This
is accomplished by changing the value of the <code>eclipse.product</code>
property as shown here.</p>
<blockquote>
<pre>eclipse.product = <font style="background-color: yellow" color="#0000ff">org.eclipse.ui.examples.rcp.browser.product</font> </pre>
</blockquote>
<p>As described in <a href="#product_branding">Product branding</a> your <code>products</code>
extension point should point to your <code>applications</code> extension point.
Setting the value of this property will select your branding as well as your
application.
<h3>Replacing the splash screen</h3>
<p>The splash screen (shown while the program starts) is contained in one file
that is usually found in the plug-in declaring the product. It must be called <b>splash.bmp</b>
and must be a .BMP file. There are no constraints regarding the size but for
reference the standard Eclipse splash screen image is 500x330 pixels.</p>
<p>The splash screen is selected based on the value of the <code>osgi.splashPath</code>
property as shown here.
<blockquote>
<pre>osgi.splashPath = <font style="background-color: yellow" color="#0000ff">platform:/base/plugins/org.eclipse.ui.examples.rcp.browser</font> </pre>
</blockquote>
<p>When using <code>platform:</code> style URLs make sure that the plug-in
referenced is in the plug-ins folder and that it is a sibling of the startup.jar.</p>
<p>To use NL'ed splash screens the locale specific images should be placed in a <code>nl</code>
directory within the plug-in's directory. For example, a splash screen for the <code>fr_FR</code>
locale would be placed within the plug-in's directory as <code>nl/fr/FR</code>,
e.g.,
<blockquote>
<pre>org.eclipse.ui.examples.rcp.browser/
nl/
fr/
FR/
splash.bmp </pre>
</blockquote>
<h3>Replacing the launcher's icon</h3>
<p>Changing the icon associated with the launcher requires modification to the
executable. We will also need to convert the icons into a resource that can be
used by the executable.</p>
<p>This process varies by platform, the following sections explain the procedure
for the Windows and Linux platforms. In both cases you should start by
extracting the file <code>eclipse/plugins/org.eclipse.platform.source_3.0.0/src/org.eclipse.platform_3.0.0/launchersrc.zip</code>
found in the SDK. In the following sections, we will work with the <code>library/</code>
directory and once we are finished we will copy the resulting executable back to
the Browser application.</p>
<h4>Creating the graphic resources for our executable</h4>
<p><img src="images/win_only.gif" width="51" height="13">&nbsp;Windows
executable programs can have an associated icon(s). To create our icon we first
need to replace several .BMP graphics located in the <code>library</code>
directory. These graphics represent 16x16, 32x32 and 48x48 pixel versions of
both low color and high color graphics. In the <code>library/</code> directory
replace the following files:</p>
<ul>
<li>icon16_basic.bmp</li>
<li>icon16_full.bmp</li>
<li>icon32_basic.bmp</li>
<li>icon32_full.bmp</li>
<li>icon48_basic.bmp</li>
<li>icon48_full.bmp</li>
</ul>
<p>Using an appropriate graphics tool (e.g. ICONPRO provided in the MSDN),
combine these graphics into a single .ICO (icon) file called <code>eclipse.ico</code>
and replace <code>library/win32/eclipse.ico</code> with your new eclipse.ico
file. The <code>eclipse.ico</code> is referenced by the file <code>library/win32/eclipse.rc</code>
which is automatically used when the build script is run. Once the build script
has finished we will have a new program executable with an associated icon.</p>
<p><img src="images/linux_only.gif" width="51" height="13">&nbsp;Linux does not
directly associate an icon with an executable program however we can include an
icon that users can use when associating a shortcut with the program. Use your
favorite graphics editor to create an xpm graphic representing your program icon
and place it into <code>library/icon.xpm</code>. Once we have built the
executable we will copy both the executable and the <code>.xpm</code> file to
the <code>eclipse/</code> root directory of the platform runtime build.</p>
<h4>Building the executable</h4>
<p>Executable icon in hand, it's time to make the executable. We will continue
to work with the <code>library/</code> directory and once we have created our
executable we will copy it to the <code>eclipse/</code> root directory of the
runtime platform build. The process for creating the program executable is
different and a build script is provided in each subfolder to help make the
process easier.</p>
<h4>Preparing the build script</h4>
<p><img src="images/win_only.gif" width="51" height="13">&nbsp;In the <code>library/win32</code>
directory you will find the build script <code>build.bat</code>. We will need to
edit this build file to point it to the location of your C compiler. To do this,
simply uncomment the following lines (by removing <code>rem</code>) and modify <code>MSVC_HOME</code>
to point to the root directory of your compiler installation.</p>
<blockquote>
<pre>rem IF NOT &quot;%MSVC_HOME%&quot;==&quot;&quot; GOTO MAKE
rem set MSVC_HOME=k:\dev\products\msvc60\vc98
rem call %MSVC_HOME%\bin\vcvars32.bat </pre>
</blockquote>
<p>This script has been tested with Microsoft® Visual C/C++ Compiler 6.0
however it is possible that you may need to make additional modifications for
your compiler.</p>
<p><img src="images/linux_only.gif" width="51" height="13">&nbsp;The Linux build
script (<code>build.csh)</code> has been tested against GNU C and C++ Compiler.
You typically should not need to make any changes to the Linux build script.</p>
<h4>Running the build script</h4>
<p>The build script takes two arguments, the filename of the executable file to
create (output) and the title (name) of your program. If the program name has
spaces in it (as in the example below) you will need to put double-quotes around
it.</p>
<p>In the example below the program name <i>RCP Browser</i> will be shown in the
task bar while the program is starting.</p>
<p><img src="images/win_only.gif" width="51" height="13">&nbsp;On Windows you
can run the build script (<code>build.bat</code>) as shown below. Prior to
running the build script you should run once using the <code>clean</code> target
to remove any artifacts from previous builds. This example will create an
executable file named <code>rcp browser.exe</code> with the icon we created
above.</p>
<blockquote>
<pre>build -output &quot;rcp browser.exe&quot; -name &quot;RCP Browser&quot; </pre>
</blockquote>
<p><img src="images/linux_only.gif" width="51" height="13">&nbsp;On Linux you
can run the build script (<code>build.csh)</code> as shown below. This example
will create an executable file named <i>rcp browser</i>. On Linux an icon is not
automatically associated with the executable.</p>
<blockquote>
<pre>csh build.csh -output &quot;rcp browser&quot; -name &quot;RCP Browser&quot; </pre>
</blockquote>
<h4>Replacing the existing executable</h4>
<p>Now that you have your own executable, you can copy it to the
code&gt;eclipse/ root directory of the browser example. It is a good idea to
remove the previous executable so that the user won't be confused on which to
run.</p>
<p><img src="images/linux_only.gif" width="51" height="13">&nbsp;On Linux we
also need to copy the <code>icon.xpm </code>(we created above) to the <code>eclipse/
</code>root replacing the one already found there.</p>
<p><img src="images/TryIt.gif" width="61" height="13">&nbsp;Start your
application by running the executable you just built. Confirm that it starts
properly and that your icons, splash screen, and program name are shown during
the application launch process.
<h2><a name="optional_branding">Optional branding</a></h2>
<p>Previous sections have discussed changes that all applications will want to
make in order to present a customized brand. In this section we discuss some
optional aspects of branding such as customizing the about dialog, applying your
own default preferences, and selecting a special presentation.</p>
<h3><b>The about dialog</b></h3>
<p>Both the image and the text in the main about dialog are subject to product
level branding.</p>
<p><img name="About dialog" src="images/about.png" width="479" height="281">
<p>These values are set from properties in your <code>products</code> extension
point as shown here</p>
<blockquote>
<pre>&lt;extension ...
&lt;product ...
&lt;property
name=&quot;aboutImage&quot;
value=<font style="background-color: yellow" color="#0000ff">&quot;icons/alt_about.gif&quot;</font>/&gt;
&lt;property
name=&quot;aboutText&quot;
value=<font style="background-color: yellow" color="#0000ff">&quot;The about dialog text can contain links such as http://www.eclipse.org.&quot;</font>/&gt;
&lt;property ... </pre>
</blockquote>
<p>The absolute maximum size for an the about image is 500x330 pixels. However,
the value of the about text property will only be displayed if the about image
is no larger than 250x300 pixels.</p>
<h3>Special preferences settings used by the product</h3>
<p>Although not shown in this example it is also possible to specify a set of
defaults that should be used with the product. For example, the preference
settings might be used to specify an alternate presentation factory. The
preferences should be stored in a file which is pointed to by the <i>preferenceCustomization</i>
property. See <a href="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/platform-ui-home/rcp/index.html#rcp_and_r21">Eclipse
Rich Client Platform</a> for an example.</p>
<h3>The <code>.eclipseproduct</code> marker file</h3>
<p>The branding of the application would not be complete without updating <code>eclipse/.eclipseproduct</code>.
This marker file is a <code>java.io.Properties</code> format file that indicates
the name, id, and version of the product. It also controls things like the
default configuration area inside the user home folder, which ensure a
separation of the configuration information among products.</p>
<p>Ensure the file exists in you <code>eclipse/</code> directory and contains:</p>
<blockquote>
<pre>name=<font style="background-color: yellow" color="#0000ff">Branded RCP Browser Example</font>
id=<font style="background-color: yellow" color="#0000ff">org.eclipse.ui.examples.rcp.browser.product</font>
version=<font style="background-color: yellow" color="#0000ff">3.0.0</font> </pre>
</blockquote>
<h3>Presentations</h3>
<p>A very powerful way to supply branding to your application is to create your
own presentation. Supplying your own <a href="http://help.eclipse.org/help30/topic/org.eclipse.platform.doc.isv/reference/extension-points/org_eclipse_ui_presentationFactories.html">presentationFactory</a>
allows you to change all aspects of your application's UI. You can find an
example of using the R21 presentation on the <a href="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/platform-ui-home/rcp/index.html#rcp_and_r21">Eclipse
RCP page</a>.
<h3>Intro page</h3>
<p>Eclipse allows you to supply an extension point to provide a customized intro
experience to users of your application. Explore the Eclipse help system for
more information on how to use the <a href="http://help.eclipse.org/help30/topic/org.eclipse.platform.doc.isv/reference/extension-points/org_eclipse_ui_intro.html">org.eclipse.ui.intro</a>
extension.
<h2><a name="troubleshooting">Troubleshooting</a></h2>
<h4><a name="osgi_bundles"></a><b>Application &quot;...&quot; could not be found
in the registry. The applications available are: &lt;NONE&gt;</b></h4>
<p>Use the error log to check that all pre-requisite plug-ins were successfully
resolved. The <code>osgi.bundles</code> property lists the plug-ins that eclipse
installs and runs.</p>
<p>Typically only <code>org.eclipse.core.runtime</code> and <code>org.eclipse.update.configurator</code>
are listed. The update configurator will discover and install all plug-ins in
the <code>plugins</code> directory. If you aren't using <code>org.eclipse.update.configurator</code>
then list all necessary plug-ins in the <code>osgi.bundles</code> property.</p>
<p>A typical RCP list might look like:</p>
<pre>osgi.bundles = org.eclipse.core.runtime@2:start, org.eclipse.core.expressions, \
org.eclipse.help, org.eclipse.jface, org.eclipse.osgi.services, \
org.eclipse.osgi, org.eclipse.swt, org.eclipse.ui.workbench, \
org.eclipse.ui, org.eclipse.swt.win32, org.eclipse.swt.gtk, \
org.eclipse.swt.gtk64, org.eclipse.swt.carbon, \
org.eclipse.swt.motif</pre>
<h4><a name="no_app_id"></a><b>No application id has been found.</b></h4>
<p>This happens when eclipse cannot find the application to run. This could
happen if the product cannot be found or the default application specified in
the product extension is not found. Check for typos in both these ids.</p>
<h4><a name="app_id_typo"></a><b>Application &quot;...&quot; could not be found
in the registry. The applications available are: ...</b></h4>
<p>This is most likely caused by a typo in the application id. If you are using
your product's default application then check the <i>application</i> attribute
in the product extension. Otherwise check the <code>eclipse.application</code>
property in the <code>config.ini</code> file. The value must match the id
defined in some application extension.</p>
<h4><a name="product_id_typo"></a><b>No branding in application</b></h4>
<p>This happens when the product cannot be found check the <code>config.ini</code>
file for typos in the value of <code>eclipse.product</code>.</p>
<h4><a name="clean"></a><b>Changes ignored</b></h4>
<p>If changes to <code>plugin.xml</code> or <code>plugin.properties</code> are
not recognized then try running once with the <code>-clean</code> command line
option. This will remove stale cache files to ensure they are regenerated from
the newest information. This option is only required during development when the
plug-in manifest is changing it will not be needed when your product is
deployed.</p>
<h2>Conclusion</h2>
<p>We have shown how to replace the basic units of branding to make your product
look like your own. This included such items as the splash screen, about dialog
and the icon and name associated with the launcher.</p>
<h2>Other Resources</h2>
<ul>
<li><a href="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/platform-ui-home/rcp/index.html">The
Eclipse Rich Client Platform</a> page</li>
<li><u>The Java Developers Guide to Eclipse</u> by Jim D'Anjou (Addison
Wesley, 2003)</li>
</ul>
<h3>From the Eclipse Help System</h3>
<ul>
<li><a href="http://help.eclipse.org/help30/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/product_def_nl.htm">Locale
specific files</a></li>
<li>The <a href="http://help.eclipse.org/help30/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/extension-points/org_eclipse_core_runtime_applications.html"><code>org.eclipse.core.runtime.applications</code></a>
extension.</li>
<li>The <a href="http://help.eclipse.org/help30/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/extension-points/org_eclipse_core_runtime_products.html"><code>org.eclipse.core.runtime.products</code></a>
extension.</li>
<li>The <a href="http://help.eclipse.org/help30/topic/org.eclipse.platform.doc.isv/reference/extension-points/org_eclipse_ui_intro.html"><code>org.eclipse.ui.intro</code></a>
extension.</li>
<li>The <a href="http://help.eclipse.org/help30/topic/org.eclipse.platform.doc.isv/reference/extension-points/org_eclipse_ui_presentationFactories.html"><code>org.eclipse.ui.presentationFactory</code></a>
extension.</li>
</ul>
<h3>From the &quot;<a href="http://www.eclipsefaq.org" target="_blank">Official
Eclipse FAQs</a>&quot; book</h3>
<ul>
<li><a href="http://www.eclipsefaq.org/chris/faq/html/faq241.html" target="_blank">FAQ
241 -- What is an Eclipse application?</a></li>
<li><a href="http://www.eclipsefaq.org/chris/faq/html/faq250.html" target="_blank">FAQ
250 -- What is an Eclipse product?</a></li>
<li><a href="http://www.eclipsefaq.org/chris/faq/html/faq251.html" target="_blank">FAQ
251 -- What is the difference between a product and an application?</a></li>
</ul>
<p><small>Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc.
in the United States, other countries, or both.</small></p>
<p><small>Microsoft and Windows are trademarks of Microsoft Corporation in the United
States, other countries, or both.</small></p>
</body>
</html>
static/articles/Article-Branding/images/TryIt.gif 0 → 100644
View file @ 49b7b027
static/articles/Article-Branding/images/TryIt.gif

309 B

static/articles/Article-Branding/images/about.png 0 → 100644
View file @ 49b7b027
static/articles/Article-Branding/images/about.png

29.6 KiB

static/articles/Article-Branding/images/alt16.gif 0 → 100644
View file @ 49b7b027
static/articles/Article-Branding/images/alt16.gif

637 B

static/articles/Article-Branding/images/alt32.gif 0 → 100644
View file @ 49b7b027
static/articles/Article-Branding/images/alt32.gif

1.16 KiB

static/articles/Article-Branding/images/alt_about.gif 0 → 100644
View file @ 49b7b027
static/articles/Article-Branding/images/alt_about.gif

9.12 KiB

static/articles/Article-Branding/images/idea.jpg 0 → 100644
View file @ 49b7b027
static/articles/Article-Branding/images/idea.jpg

4.98 KiB

static/articles/Article-Branding/images/linux_only.gif 0 → 100644
View file @ 49b7b027
static/articles/Article-Branding/images/linux_only.gif

174 B

static/articles/Article-Branding/images/proposal.gif 0 → 100644
View file @ 49b7b027
static/articles/Article-Branding/images/proposal.gif

3.45 KiB

static/articles/Article-Branding/images/title.png 0 → 100644
View file @ 49b7b027
static/articles/Article-Branding/images/title.png

2.74 KiB

static/articles/Article-Branding/images/win_only.gif 0 → 100644
View file @ 49b7b027
static/articles/Article-Branding/images/win_only.gif

221 B

static/articles/Article-Branding/images/windowImage.png 0 → 100644
View file @ 49b7b027
static/articles/Article-Branding/images/windowImage.png

2.78 KiB

static/articles/Article-BuildYourOwnDSL/article.xml 0 → 100644
View file @ 49b7b027
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<article id="article">
<articleinfo>
<title>Build your own textual DSL with Tools from the Eclipse Modeling
Project</title>
<releaseinfo role="SVN">$Id: article.xml,v 1.3 2008/07/23 16:49:44 wbeaton
Exp $</releaseinfo>
<date>April 18, 2008</date>
<authorgroup>
<author>
<firstname>Peter</firstname>
<surname>Friese</surname>
<affiliation>
<orgname>itemis AG</orgname>
<address>
<email>peter.friese@itemis.de</email>
</address>
</affiliation>
</author>
<author>
<firstname>Sven</firstname>
<surname>Efftinge</surname>
<affiliation>
<orgname>itemis AG</orgname>
<address>
<email>sven.efftinge@itemis.de</email>
</address>
</affiliation>
</author>
<author>
<firstname>Jan</firstname>
<surname>Köhnlein</surname>
<affiliation>
<orgname>itemis AG</orgname>
<address>
<email>jan.koehnlein@itemis.de</email>
</address>
</affiliation>
</author>
</authorgroup>
<copyright>
<year>2008</year>
<holder>itemis AG. All rights reserved.</holder>
</copyright>
<abstract>
<para>Domain Specific Languages (DSLs) are a hot topic nowadays. While
creating internal DSLs is no big deal, external DSLs have been said to
be hard to create. In this tutorial we will show you how easy it is to
create your own DSL with tools from the Eclipse Modeling Project (EMP)
in less than one hour.</para>
</abstract>
<legalnotice>
<para>Java and all Java-based trademarks are trademarks of Sun
Microsystems, Inc. in the United States, other countries, or
both.</para>
<para>Linux is a trademark of Linus Torvalds in the United States, other
countries, or both.</para>
<para>Microsoft is a trademark of Microsoft Corporation in the United
States, other countries, or both.</para>
<para>UNIX is a registered trademark of The Open Group in the United
States and other countries.</para>
<para>Other company, product, or service names may be trademarks or
service marks of others.</para>
</legalnotice>
</articleinfo>
<section id="introduction">
<title>Introduction</title>
<para>The purpose of this tutorial is to illustrate the definition of
external DSLs using tools from the Eclipse Modeling Project (EMP). The
main focus is on the <emphasis>Xtext</emphasis> framework. We will start
by defining our own DSL in an <emphasis>Xtext</emphasis> grammar. Then we
will use the <emphasis>Xtext</emphasis> framework to generate a parser, an
<emphasis>Ecore-based</emphasis> metamodel and a textual editor for
Eclipse. Afterwards we will see how to refine the DSL and its editor by
means of <emphasis>Xtend</emphasis> extensions. Finally, we will learn how
one can generate code out of textual models using the template language
<emphasis>Xpand</emphasis>.</para>
<para>The actual content of this example is rather trivial—our DSL will
describe entities with properties and references between them from which
we generate Java classes according to the JavaBean conventions—a rather
typical data model. In a real setting, we might also generate persistence
mappings, etc. from the same models. We skipped this to keep the tutorial
simple.</para>
</section>
<section id="environment">
<title>Setting up the Environment</title>
<para>To follow this tutorial, you will need to install the following
components <itemizedlist>
<listitem>
<simpara>A Java 5 or 6 SDK. Download it at <xref
linkend="java_download" /> or use another SDK that suits your
environment.</simpara>
</listitem>
<listitem>
<simpara>Eclipse SDK 3.4 (From the "Ganymede" release). You can
download it from <xref linkend="eclipse_ganymede" />. Install by
simply unpacking the archive.</simpara>
</listitem>
<listitem>
<simpara>openArchitectureWare 4.3. Download the ZIP file from <xref
linkend="oaw_download" /> or point your eclipse update manager to
<xref linkend="oaw_update_site" />.</simpara>
</listitem>
</itemizedlist></para>
<para>The source code for the samples developed in this article can be
downloaded from <xref linkend="solution" />.</para>
</section>
<section id="defininig_the_dsl">
<title>Defining the DSL</title>
<section id="creating_an_xtext_project">
<title>Creating an Xtext Project</title>
<para>Xtext projects are based on the well-known Eclipse plug-in
architecture. In fact, to create a new textual DSL with Xtext, you'll
need up to three projects that depend on each other. But fear not -
Xtext comes with a handy wizards to get you up and running in no
time.</para>
<para>To create a new Xtext project, <itemizedlist>
<listitem>
<simpara>Start up Eclipse 3.4 with oAW 4.3 installed (see <xref
linkend="environment" />) in a fresh workspace and close the
welcome screen</simpara>
</listitem>
<listitem>
<simpara>Select <emphasis role="bold">File &gt; New... &gt;
Project... Xtext Project</emphasis></simpara>
</listitem>
<listitem>
<simpara>Specify the project settings in the wizard dialog. Since
you started in a fresh workspace, the wizard should provide
sensible defaults. See the Xtext reference documentation for a
detailed overview of what all those settings mean.</simpara>
</listitem>
<listitem>
<simpara>Click <emphasis role="bold">Finish</emphasis></simpara>
</listitem>
</itemizedlist></para>
<para>The wizard creates three projects, <filename>my.dsl</filename>,
<filename>my.dsl.editor</filename>, and
<filename>my.dsl.generator</filename>: <itemizedlist>
<listitem>
<simpara><emphasis role="bold">my.dsl</emphasis> is the language
project, in which we will define the grammar for our DSL. After
running the Xtext generator, this model also contains a parser for
the DSL and a metamodel backing the language.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="bold">my.dsl.editor</emphasis> will
contain the DSL editor. Since we have not yet defined a grammar,
this project is still empty. It will be filled by the Xtext
generator later.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="bold">my.dsl.generator</emphasis>
contains an openArchitectureWare code generator skeleton. Later in
this tutorial, you will write a couple of templates that process
models created with your DSL editor.</simpara>
</listitem>
</itemizedlist></para>
</section>
<section id="defining_the_grammar">
<title>Defining the Grammar</title>
<para>Now that you have created a new Xtext project, you can define the
grammar for your DSL. The grammar specifies the metamodel
<emphasis>and</emphasis> the concrete syntax for your domain specific
language. This allows for fast roundtrips and an incremental development
of your language, as you will see later.</para>
<para>To specify the grammar, you will be using the Xtext grammar
language. The Xtext documentation contains an extensive reference of all
grammar elements. However, to make it easier for you to follow along
this tutorial, we have included the relevant grammar rules here.</para>
<para>In this tutorial, we will develop a DSL for entities (since
entities are something most developers know quite well). <itemizedlist>
<listitem>
<simpara>Open the Xtext grammar definition
<filename>my.dsl/src/mydsl.xtxt</filename></simpara>
</listitem>
<listitem>
<simpara>And type in the following grammar definition:</simpara>
</listitem>
</itemizedlist></para>
<programlisting>
Model:
(types+=Type)*; <co id="rule.model" />
Type:
DataType | Entity; <co id="rule.type" />
DataType:
"datatype" name=ID; <co id="rule.datatype" />
Entity:
"entity" name=ID "{"
(features+=Feature)* <co id="rule.entity" />
"}";
Feature:
type=[Type|ID] name=ID; <co id="rule.feature" />
</programlisting>
<calloutlist>
<callout arearefs="rule.model">
<para>The <emphasis role="bold">Model</emphasis> rule specifies that
a model contains zero or more <emphasis
role="bold">Types</emphasis>.</para>
</callout>
<callout arearefs="rule.type">
<para>The <emphasis role="bold">Type</emphasis> rule is an abstract
rule. It specifies that a <emphasis role="bold">Type</emphasis> may
either be a <emphasis role="bold">DataType</emphasis> or an
<emphasis role="bold">Entity</emphasis></para>
</callout>
<callout arearefs="rule.datatype">
<para>The <emphasis role="bold">DataType</emphasis> rule specifies
that a <emphasis role="bold">DataType</emphasis> starts with the
literal <emphasis role="bold">datatype</emphasis>, followed by a
name. The name must comply with the (built-in) rule for identifiers
(that is, only characters followed by zero or more characters mixed
with any number of numbers are valid).</para>
</callout>
<callout arearefs="rule.entity">
<para>The <emphasis role="bold">Entity</emphasis> rule specifies
that an <emphasis role="bold">Entity</emphasis> starts with the
literal <emphasis role="bold">entity</emphasis>, followed by the
name of the entity (which, in turn, must be an identifier). An
entity definition has a body which is surrounded by curly braces.
The body may then contain any number (zero or more) of <emphasis
role="bold">Feature</emphasis>s.</para>
</callout>
<callout arearefs="rule.feature">
<para>A <emphasis role="bold">Feature</emphasis> has a reference to
a <emphasis role="bold">Type</emphasis> and a name. The reference to
<emphasis role="bold">Type</emphasis> is particularly interesting,
because by appending the <emphasis>|ID</emphasis> modifier, we point
out that the reference to <emphasis role="bold">Type</emphasis> will
be determined by an ID.</para>
</callout>
</calloutlist>
<para>Your grammar should now look like in <xref
linkend="xtext_dsl_grammar" />.</para>
<figure id="xtext_dsl_grammar">
<title>DSL grammar</title>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="images/3_grammar.png" scale="60" />
</imageobject>
<imageobject role="html">
<imagedata fileref="images/3_grammar.png" />
</imageobject>
</mediaobject>
</figure>
</section>
<section id="generating_the_dsl_editor">
<title>Generating the DSL Editor</title>
<para>Having specified the grammar, we can now generate the DSL editor.
<itemizedlist>
<listitem>
<simpara>Right-click inside the Xtext grammar editor to open the
context menu.</simpara>
</listitem>
<listitem>
<simpara>Select <emphasis role="bold">Generate Xtext
Artifacts</emphasis> to generate the DSL parser, the corresonding
metamodel and, last but not least, the DSL editor.</simpara>
</listitem>
</itemizedlist></para>
<figure id="generate_xtext_artifacts">
<title>Generate Xtext artifacts</title>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="images/4_generate_xtext_artifacts.png"
scale="60" />
</imageobject>
<imageobject role="html">
<imagedata fileref="images/4_generate_xtext_artifacts.png" />
</imageobject>
</mediaobject>
</figure>
</section>
<section id="running_the_editor">
<title>Running the Editor</title>
<para>To run the generated editor, you have to start a new Eclipse
workbench with the DSL plug-ins enabled. <itemizedlist>
<listitem>
<simpara>Choose <emphasis role="bold">Run -&gt; Run
Configurations...</emphasis></simpara>
</listitem>
<listitem>
<simpara>The <emphasis>Run Configuraton</emphasis> dialog appears.
Choose <emphasis role="bold">New</emphasis> from the context menu
of <emphasis role="bold">Eclipse Application</emphasis></simpara>
</listitem>
<listitem>
<simpara>Choose <emphasis role="bold">New</emphasis> from the
context menu of <emphasis role="bold">Eclipse
Application</emphasis>.</simpara>
</listitem>
<listitem>
<simpara>Go to the <emphasis>Arguments</emphasis> tab and enter
<emphasis role="bold">-Xmx256m</emphasis> in the <emphasis>VM
arguments</emphasis> field to increase the maximum heap size of
the new Eclipse workbench.</simpara>
</listitem>
<listitem>
<simpara>Start the new Eclipse workbench by clicking the <emphasis
role="bold">Run</emphasis> button.</simpara>
</listitem>
</itemizedlist> <figure id="new_config">
<title>Setting up a new Eclipse workbench to test the DSL
plug-ins</title>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="images/4a_new_run_config.png" scale="60" />
</imageobject>
<imageobject role="html">
<imagedata fileref="images/4a_new_run_config.png" />
</imageobject>
</mediaobject>
</figure> <figure id="new_eclipse_app">
<title>Creating a new Eclipse run configuration</title>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="images/4b_new_eclipse_application.png"
scale="60" />
</imageobject>
<imageobject role="html">
<imagedata fileref="images/4b_new_eclipse_application.png" />
</imageobject>
</mediaobject>
</figure> <figure id="increase_heapsize">
<title>Increasing maximum heap size</title>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="images/4c_increase_heap_memory.png"
scale="60" />
</imageobject>
<imageobject role="html">
<imagedata fileref="images/4c_increase_heap_memory.png" />
</imageobject>
</mediaobject>
</figure></para>
</section>
<section id="exploring_the_editor">
<title>Taking it for a spin</title>
<para>You should now see the same workspace as before. To check out the
DSL editor, create a new <emphasis>mydsl</emphasis> project and model in
the runtime instance:</para>
<itemizedlist>
<listitem>
<simpara>Select <emphasis role="bold">File &gt; New... &gt; Other...
&gt; mydsl Project</emphasis> to create a new
<emphasis>mydsl</emphasis> project.</simpara>
</listitem>
<listitem>
<simpara>Click <emphasis role="bold">Next</emphasis> to proceed to
the next wizard page.</simpara>
</listitem>
<listitem>
<simpara>Leave the project name as is (it should read
<emphasis>mydslproject</emphasis>) and click <emphasis
role="bold">Finish</emphasis> to create the project.</simpara>
</listitem>
</itemizedlist>
<para>The wizard will now create a new project for you, including an
empty sample model.</para>
<para>Key in the following model to see your editor in action. Note how
the outline reflects the contents of your model. While typing, try using
the content assist feature by pressing <keycombo>
<keycap>CTRL</keycap>
<keycap>Space</keycap>
</keycombo>.</para>
<programlisting>
datatype String
datatype String
entity Person {
String name
String lastName
Address home
Address business
}
entity Address {
String street
String zip
String city
}
</programlisting>
<para>Xtext-based editors support a number of features right out of the
box:</para>
<itemizedlist>
<listitem>
<para>Syntax coloring</para>
</listitem>
<listitem>
<para>Code completion (press <keycombo>
<keycap>CTRL</keycap>
<keycap>Space</keycap>
</keycombo> to invoke)</para>
</listitem>
<listitem>
<para>Navigation (either by holding the <keycap>CTRL</keycap> key
and left-clicking an identifier or by pressing the
<keycap>F3</keycap> key when the cursor is on an identifier)</para>
</listitem>
<listitem>
<para>Find References (place the cursor on an identifier and press
<keycombo>
<keycap>CTRL</keycap>
<keycap>SHIFT</keycap>
<keycap>G</keycap>
</keycombo>)</para>
</listitem>
<listitem>
<para>Folding</para>
</listitem>
<listitem>
<para>Outline</para>
</listitem>
<listitem>
<para>Quick Outline (press <keycombo>
<keycap>CTRL</keycap>
<keycap>O</keycap>
</keycombo>)</para>
</listitem>
<listitem>
<para>Syntax checking / Error markers</para>
</listitem>
</itemizedlist>
<para>It is important to note that all those features have been derived
from the grammar you defined earlier. If you make changes to the
grammar, the generated tooling will reflect these changes as well, as
you will see in a minute.</para>
</section>
</section>
<section id="refining_the_dsl">
<title>Refining the DSL</title>
<para>While Xtext-based DSL editors have a collection of great feature
that come for free, they can be easily customized to your needs. In the
following section, we will add some extra features that improve your
editor's usability. As you will see, implementing those features will not
cost us much effort.</para>
<section id="adjusting_code_completion">
<title>Adjusting code completion</title>
<para>First, let's enhance code completion. Let's assume you want to
assist the user of your editor in choosing the right data types. In most
projects, there's probably only about five or six different data types
in use, so why not provide them in the suggestion list for the
<varname>datatype</varname> grammar rule?</para>
<para>To do so, open
<filename>my.dsl.editor/src/org.example.dsl/ContentAssist.ext</filename>
and insert the following lines at the end of the file:</para>
<programlisting>
/* proposals for Feature DataType::name */
List[Proposal] completeDataType_name<co id="extension.name" />(emf::EObject ctx, String prefix) :
{
newProposal("String"),
newProposal("Date"),
newProposal("Boolean"),
newProposal("Long"),
newProposal("int")
};
</programlisting>
<calloutlist>
<callout arearefs="extension.name">
<para>The name of he extension function must match the following
rule: <emphasis role="bold">complete&lt;name of the
metatype&gt;_&lt;name of the attribute to be
completed&gt;</emphasis>. In this sample, the extension function
will be invoked as soon as the user requests content assist for the
name of a <emphasis role="bold">DataType</emphasis>.</para>
</callout>
</calloutlist>
<para>After saving the extension file, the DSL editor display the new
proposals:</para>
<figure id="enhanced_CA">
<title>Enhanced content assist in action</title>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="images/7_enhanced_CA.png" scale="60" />
</imageobject>
<imageobject role="html">
<imagedata fileref="images/7_enhanced_CA.png" />
</imageobject>
</mediaobject>
</figure>
</section>
<section id="refining_checks">
<title>Defining constraints for your model</title>
<para>You may have noticed that although the generated DSL editor
detects syntax violations in your models, it is still possible to define
illegal models, e.g. by defining several datatype definitions with the
same name.</para>
<para>The <emphasis>Check</emphasis> language from the
openArchitectuerWare stack can be used to define constraints that ensure
the validity of your models.</para>
<para>Let's define a constraint that ensures that a model does not
contain more than one data type with the same name. To do so, open
<filename>my.dsl/src/org.example.dsl/Checks.chk</filename> and add the
following contraint to the end of the file:</para>
<programlisting>
context Type ERROR "Duplicate type detected: " + this.name :
allElements()<co id="allElements" />.typeSelect(Type)<co id="typeSelect" />.select(e|e.name == this.name).size ==1;
</programlisting>
<para>This constraint basically means the following: <itemizedlist>
<listitem>
<para>From the collection of <emphasis>all model
elements</emphasis>,</para>
</listitem>
<listitem>
<para>select all elements that are of type <emphasis
role="bold">Type</emphasis> (i.e, all <emphasis
role="bold">DataTypes</emphasis> and all <emphasis
role="bold">Entities</emphasis>).</para>
</listitem>
<listitem>
<para>Of the resulting collection, select all elements whose name
equals the name of the current <emphasis
role="bold">Type</emphasis>.</para>
</listitem>
<listitem>
<para>Finally, check whether the size of the resulting collection
is exactly one (1).</para>
</listitem>
</itemizedlist> In other words: each model may only have exactly one
<emphasis role="bold">Type</emphasis> with the same name.</para>
<para>After saving the check file, the DSL editor now issues an error if
you enter two types with the same name:</para>
<figure id="constraint_validation">
<title>Constraint fails on duplicate data types</title>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="images/8_constraint_validation.png" scale="60" />
</imageobject>
<imageobject role="html">
<imagedata fileref="images/8_constraint_validation.png" />
</imageobject>
</mediaobject>
</figure>
</section>
</section>
<section>
<title>Generating code</title>
<para>Now, that we have a DSL, we may want to do something useful with it.
DSLs are essentially small programming languages. A programming language
has to be understandable by a computer. There are basically two ways to
make a language "understandable" by a computer. The first one is to write
a compiler which transforms expressions made in one language into another
language, which is already understandable by a computer. For example, a
Java compiler transforms Java programs to bytecode programs. Bytecode is
understandable, because there are VMs which translate expressions in Java
bytecode into more native instructions. This is usually done at runtime.
Translating a language at runtime is called interpretation (ignoring
special cases like just-in-time compilation here).</para>
<para>With Xtext, models one can either create a compiler (also called
generator) or an interpreter. Although there are good reasons for both
approaches, we will just discuss how one creates a generator in this
tutorial.</para>
<section>
<title>Code generation with Xpand</title>
<para>The Xtext wizard already created a generator project for us. We
are going to write an Xpand template, which generates simple JavaBeans
from our entities. It is assumed, that there is a Java data type
corresponding to the data types used in the models (e.g. <emphasis
role="bold">String</emphasis>). So, we do not need to care about mapping
data types.</para>
<para>So just open the Xpand template (<emphasis
role="bold">Main.xpt</emphasis>) and modify it like this:</para>
<figure id="xtext_tutorial_xpand_tenplate">
<title>Xpand template</title>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="images/9_xpand_template.png" scale="60" />
</imageobject>
<imageobject role="html">
<imagedata fileref="images/9_xpand_template.png" />
</imageobject>
</mediaobject>
</figure>
<para>The definition <emphasis role="bold">main</emphasis> is invoked
from the workflow file. It is declared for elements of type <emphasis
role="bold">mydsl::Model</emphasis>, which corresponds to the root node
of our DSL models. Within this definition, another definition (<emphasis
role="bold">javaBean</emphasis>) is called (<emphasis
role="bold">«EXPAND javaBean...»</emphasis>) for each model element
(<emphasis role="bold">...FOREACH...</emphasis>) contained in the
reference '<emphasis role="bold">types</emphasis>' of <emphasis
role="bold">Model</emphasis> which is of type <emphasis
role="bold">Entity</emphasis>. (<emphasis
role="bold">typeSelect(Entity)</emphasis>).</para>
<para>The definition <emphasis role="bold">javaBean</emphasis> is
declared for elements of type <emphasis role="bold">Entity</emphasis>.
In this definition, we open a file («FILE ...»). The path name of the
file is defined by an expression. In this case, it corresponds to the
name of the entity suffixed with '<filename>.java</filename>'. It is
going to be generated into the <filename>src-gen</filename> directory
directly.</para>
<para>All text contained between <emphasis role="bold">«FILE
...»</emphasis> and <emphasis role="bold">«ENDFILE»</emphasis> will go
to the new file. <emphasis>Xpand</emphasis> provides control statements
(<emphasis role="bold">FOR</emphasis>, <emphasis
role="bold">IF</emphasis>, <emphasis role="bold">ELSEIF</emphasis>,
...), as well as evaluation of expression, in order to create the
desired code. See the openArchitectureWare reference documentation for
details.</para>
<para>To see our template in action, we have to run the code generator:
<itemizedlist>
<listitem>
<para>Locate the oAW workflow file
<emphasis>mydslproject.oaw</emphasis> in your
<emphasis>mydslproject</emphasis> plug-in.</para>
</listitem>
<listitem>
<para>Right-click on it and choose <emphasis role="bold">Run as
&gt; oAW Workflow</emphasis> from the context menu.</para>
</listitem>
<listitem>
<para>You can see the generator running and logging into the
<emphasis>Console</emphasis> view.</para>
</listitem>
<listitem>
<para>The result will be stored in a new source folder
<emphasis>src-gen</emphasis> in the
<emphasis>mydslproject</emphasis> project.</para>
</listitem>
</itemizedlist></para>
</section>
</section>
<section id="deploying_the_editor">
<title>Deploying the Editor</title>
<para>If you have finished customizing the generator and the editor, you
can deploy the DSL plug-ins to an Eclipse installation. For simplicity, we
take the one we are already running. <itemizedlist>
<listitem>
<simpara>Choose <emphasis role="bold">Export... &gt; Deployable
plug-ins and fragments...</emphasis></simpara>
</listitem>
<listitem>
<simpara>The <emphasis>Export</emphasis> dialog appears. Select the
three DSL plug-ins.</simpara>
</listitem>
<listitem>
<simpara>Enter the path to your Eclipse installation. Make sure the
selected directory contains the Eclipse executable and a folder
named <emphasis>plugins</emphasis>. Usually, the directory is called
<emphasis>eclipse</emphasis>.</simpara>
</listitem>
<listitem>
<simpara>Choose <emphasis role="bold">Finish</emphasis>.</simpara>
</listitem>
<listitem>
<simpara>Restart Eclipse.</simpara>
</listitem>
</itemizedlist> <figure id="deploy_plugins">
<title>Deployment of the DSL plug-ins</title>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="images/5_deploy_plugins.png" scale="60" />
</imageobject>
<imageobject role="html">
<imagedata fileref="images/5_deploy_plugins.png" />
</imageobject>
</mediaobject>
</figure></para>
</section>
<section>
<title>Where to go from here...</title>
<para>This tutorial ends here, but there is a lot more to know about
Xtext, Xpand, DSLs and EMP, e.g. <itemizedlist>
<listitem>
<simpara>Advanced model customization: References to elements
outside the model, configurable linking of cross-references,
etc.</simpara>
</listitem>
<listitem>
<simpara>Further customizing of the editor: Choosing font styles,
defining multiple outline views etc.</simpara>
</listitem>
<listitem>
<simpara>Integration with the Eclipse Modeling Framework (EMF), and
thereby opening to the whole world of eclipse modeling.</simpara>
</listitem>
</itemizedlist> Please consult the openArchitectureWare reference
documentation <xref linkend="oaw_reference_documentation" /> for further
information.</para>
</section>
<bibliography>
<title>Resources</title>
<biblioentry id="java_download">
<title>Sun's Java SDK</title>
<bibliosource><ulink
url="http://java.sun.com/javase/downloads/index.jsp">
http://java.sun.com/javase/downloads/index.jsp </ulink></bibliosource>
</biblioentry>
<biblioentry id="eclipse_ganymede">
<title>Eclipse 3.4</title>
<bibliosource><ulink url="http://www.eclipse.org/ganymede/">
http://www.eclipse.org/ganymede/</ulink></bibliosource>
</biblioentry>
<biblioentry id="oaw_download">
<title>openArchitectureWare download page</title>
<bibliosource><ulink url="http://www.eclipse.org/gmt/oaw/download/">
http://www.eclipse.org/gmt/oaw/download/ </ulink></bibliosource>
</biblioentry>
<biblioentry id="oaw_update_site">
<title>openArchitectureWare update site</title>
<bibliosource><ulink
url="http://www.openarchitectureware.org/updatesite/milestone/site.xml">
http://www.openarchitectureware.org/updatesite/milestone/site.xml
</ulink></bibliosource>
</biblioentry>
<biblioentry id="oaw_reference_documentation">
<title>openArchitectureWare reference documentation</title>
<bibliosource><ulink url="http://www.eclipse.org/gmt/doc/">
http://www.eclipse.org/gmt/doc/ </ulink></bibliosource>
</biblioentry>
<biblioentry id="solution">
<title>Source code for the sample developed in this article</title>
<bibliosource><ulink url="solution/mydsl.zip"> mydsl.zip
</ulink></bibliosource>
</biblioentry>
</bibliography>
</article>
\ No newline at end of file
static/articles/Article-BuildYourOwnDSL/build.xml 0 → 100755
View file @ 49b7b027
<!--
Build script for Eclipse.org Articles
$Id: build.xml,v 1.1 2008/05/15 15:26:43 wbeaton Exp $
author: Chris Aniszczyk <zx@us.ibm.com>
author: Lawrence Mandel <lmandel@ca.ibm.com>
-->
<project name="eclipse.org article (docbook)" default="build-doc" basedir=".">
<!-- ========== Properties: User Defined Options ========================= -->
<property name="article.source.name" value="article"/>
<property name="article.dest.name" value="index"/>
<property name="article.stylesheet" value="../article.xsl"/>
<property name="dest.dir" value="."/>
<property name="download.dir" value="${user.home}${file.separator}.downloads"/>
<property name="docbook.dir" value="${download.dir}${file.separator}docbook-xsl-1.71.1"/>
<property name="docbookxsl.url" value="http://downloads.sourceforge.net/docbook/docbook-xsl-1.71.1.zip"/>
<property name="build.home" value="build"/>
<!-- ========== Targets =================================================== -->
<target name="init">
<mkdir dir="${download.dir}"/>
</target>
<target name="build-doc" depends="init, get-docbook-xsl">
<echo>Building Article...</echo>
<antcall target="docbook2html"/>
</target>
<target name="check-docbook">
<available file="${download.dir}${file.separator}docbook.zip" property="hasDocbook"/>
</target>
<target name="get-docbook-xsl" description="Downloads docbook xsl" depends="init, check-docbook" unless="hasDocbook">
<echo>Downloading DocBook XSL...</echo>
<get dest="${download.dir}${file.separator}docbook.zip" src="${docbookxsl.url}"/>
<unzip src="${download.dir}${file.separator}docbook.zip" dest="${download.dir}"/>
</target>
<target name="docbook2html" depends="get-docbook-xsl">
<echo>Converting article to HTML...</echo>
<delete file="${dest.dir}${file.separator}${article.name}.html"/>
<xslt in="${article.source.name}.xml" extension="xml" out="${dest.dir}${file.separator}${article.dest.name}.html" style="${article.stylesheet}">
<xmlcatalog>
<entity
publicId="docbook.xsl"
location="${docbook.dir}${file.separator}html${file.separator}docbook.xsl"/>
</xmlcatalog>
<param name="header.rule" expression="1" />
<param name="admon.graphics.extension" expression=".gif"/>
<param name="admon.textlabel" expression="0"/>
<param name="ulink.target" expression="_new"/>
</xslt>
</target>
</project>
\ No newline at end of file
static/articles/Article-BuildYourOwnDSL/default_style.css 0 → 100644
View file @ 49b7b027
p, table, td, th { font-family: arial, helvetica, geneva; font-size: 10pt}
pre { font-family: "Courier New", Courier, mono; font-size: 10pt; background-color: #EEEEEE;}
h2 { font-family: arial, helvetica, geneva; font-size: 18pt; font-weight: bold ; line-height: 14px}
code { font-family: "Courier New", Courier, mono; font-size: 10pt}
sup { font-family: arial,helvetica,geneva; font-size: 10px}
h3 { font-family: arial, helvetica, geneva; font-size: 14pt; font-weight: bold}
li { font-family: arial, helvetica, geneva; font-size: 10pt}
h1 { font-family: arial, helvetica, geneva; font-size: 28px; font-weight: bold}
body { font-family: arial, helvetica, geneva; font-size: 10pt; clip: rect( ); margin-top: 5mm; margin-left: 3mm}
.indextop { font-size: x-large;; font-family: Verdana, Arial, Helvetica, sans-serif; font-weight: bold}
.indexsub { font-size: xx-small;; font-family: Arial, Helvetica, sans-serif; color: #8080FF}
.corner { color: #FFFFFF; font-weight: bold; }
\ No newline at end of file
static/articles/Article-BuildYourOwnDSL/files/article.xsl 0 → 100644
View file @ 49b7b027
<?xml version='1.0'?>
<!--
$Id: article.xsl,v 1.1 2008/05/15 15:26:45 wbeaton Exp $
author: Chris Aniszczyk <zx@us.ibm.com>
author: Lawrence Mandel <lmandel@ca.ibm.com>
-->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<xsl:import href="docbook.xsl" />
<xsl:param name="html.stylesheet"
select="'default_style.css'" />
<xsl:param name="admon.graphics" select="1" />
<xsl:param name="admon.graphics.path">images/</xsl:param>
<xsl:param name="admon.graphics.extension">.png</xsl:param>
<xsl:param name="suppress.navigation" select="1" />
<xsl:param name="bibliography.numbered" select="1" />
<xsl:param name="generate.toc">article nop</xsl:param>
<xsl:param name="ulink.target" select="'_new'"/>
<xsl:param name="admon.style">
<xsl:text>margin-left: 0.38in; margin-right: 0.38in;</xsl:text>
</xsl:param>
<!-- supress the releaseinfo and copyright information -->
<xsl:template match="releaseinfo | copyright"
mode="titlepage.mode">
</xsl:template>
<xsl:template name="user.header.content">
<div align="right">
&#160;
<span class="copy">
Copyright &#x00A9;<xsl:value-of select="//copyright/year[1]" />&#160;<xsl:value-of select="//copyright/holder[1]" />
</span>
</div>
</xsl:template>
<xsl:template name="article.titlepage.recto">
<h1 align="center"><xsl:value-of select="articleinfo/title"/></h1>
<blockquote>
<b>Summary</b><br/>
<xsl:value-of select="articleinfo/abstract"/> <br/>
<p>
<b>By
<xsl:for-each select="articleinfo/authorgroup/author">
<xsl:value-of select="firstname"/>&#160;<xsl:value-of select="surname"/>, <xsl:value-of select="affiliation/orgname"/><br/>
</xsl:for-each>
</b>
<xsl:apply-templates mode="article.titlepage.recto.mode" select="articleinfo/date"/>
</p>
</blockquote>
</xsl:template>
<xsl:template match="legalnotice"
mode="article.titlepage.recto.auto.mode.footnote">
<div xsl:use-attribute-sets="article.titlepage.recto.style">
<xsl:apply-templates select="."
mode="titlepage.mode"/>
</div>
</xsl:template>
<xsl:template name="process.footnotes">
<p></p>
<h3>Trademarks</h3>
<xsl:apply-templates select="articleinfo/legalnotice"
mode="article.titlepage.recto.auto.mode.footnote"/>
</xsl:template>
</xsl:stylesheet>
\ No newline at end of file

Copyright © Eclipse Foundation, Inc. All Rights Reserved.     Privacy Policy | Terms of Use | Copyright Agent