Big-Data-HPC-Platform/docs/ECLPluginForEclipse/ECL_Plugin_for_Eclipse.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book xml:base="../">
  <bookinfo>
    <title>ECL Plug-in for the Eclipse IDE</title>

    <mediaobject>
      <imageobject>
        <imagedata fileref="images/redswooshWithLogo3.jpg" />
      </imageobject>
    </mediaobject>

    <author>
      <surname>Boca Raton Documentation Team</surname>
    </author>

    <legalnotice>
      <para>We welcome your comments and feedback about this document via
      email to <email>docfeedback@hpccsystems.com</email></para>

      <para>Please include <emphasis role="bold">Documentation
      Feedback</emphasis> in the subject line and reference the document name,
      page numbers, and current Version Number in the text of the
      message.</para>

      <para>LexisNexis and the Knowledge Burst logo are registered trademarks
      of Reed Elsevier Properties Inc., used under license.</para>

      <para>HPCC Systems is a registered trademark of LexisNexis Risk Data
      Management Inc.</para>

      <para>Other products, logos, and services may be trademarks or
      registered trademarks of their respective companies.</para>

      <para>All names and example data used in this manual are fictitious. Any
      similarity to actual persons, living or dead, is purely
      coincidental.</para>

      <para><emphasis role="redbold"> </emphasis></para>
    </legalnotice>

    <xi:include href="common/Version.xml" xpointer="FooterInfo"
                xmlns:xi="http://www.w3.org/2001/XInclude" />

    <!--Release Info makes a running page footer:now an include from version.xml-->

    <xi:include href="common/Version.xml" xpointer="DateVer"
                xmlns:xi="http://www.w3.org/2001/XInclude" />

    <!--The include statement pulls in the date_ver from version.xml-->

    <corpname>HPCC Systems</corpname>

    <!--corpname never prints-->

    <xi:include href="common/Version.xml" xpointer="Copyright"
                xmlns:xi="http://www.w3.org/2001/XInclude" />

    <!--Copyright tag now gets copyright from version.xml-->

    <mediaobject role="logo">
      <imageobject>
        <imagedata fileref="images/LN_Rightjustified.jpg" />
      </imageobject>
    </mediaobject>
  </bookinfo>

  <chapter id="Eclipse_Introduction">
    <title>Introduction</title>

    <para>Eclipse is an alternative Integrated Development Environment (IDE)
    which can be used with the HPCC Systems Platform. Eclipse is open-source,
    and multi-platform. It can be used instead of the ECL IDE to write and
    execute queries into data on an HPCC cluster .</para>

    <para>The ECL plug-in is also open source.</para>

    <para>The following sections cover how to install and use the ECL plug-in
    for Eclipse.</para>

    <sect1 id="ECL_Files" role="nobrk">
      <title>Prerequisites and Requirements</title>

      <para>These are the basic requirements to run the Eclipse
      plug-in.</para>

      <sect2>
        <title>Windows Prerequisites:</title>

        <para><itemizedlist>
            <listitem>
              <para>The HPCC Client Tools (available from <ulink
              url="http://hpccsystems.com/download/free-community-edition/client-tools">http://hpccsystems.com/download/free-community-edition/client-tools</ulink>
              )</para>

              <para>This installs the ECL compiler, eclcc, command line tools,
              and related components</para>
            </listitem>

            <listitem>
              <para>The Graph Control (available from <ulink
              url="http://hpccsystems.com/download/free-community-edition/graph-control">http://hpccsystems.com/download/free-community-edition/graph-control</ulink>)</para>
            </listitem>

            <listitem>
              <para>Eclipse Indigo or later</para>
            </listitem>

            <listitem>
              <para>The ECL plug-in for Eclipse</para>

              <para><informaltable colsep="1" frame="all" rowsep="1">
                  <?dbfo keep-together="always"?>

                  <tgroup cols="2">
                    <colspec colwidth="49.50pt" />

                    <colspec />

                    <tbody>
                      <row>
                        <entry><inlinegraphic
                        fileref="images/caution.png" /></entry>

                        <entry>On a machine running Windows 7 (either the 32-
                        or 64-bit), depending on your install location, you
                        may need to start Eclipse with <emphasis>administrator
                        privileges</emphasis> for plug-ins to install
                        properly. This is necessary even if your account has
                        administrator privileges. <para>Right-click on the
                        Eclipse shortcut, then select <emphasis
                        role="bold">Run as Administrator</emphasis> from the
                        pop-up menu. </para><para>After installing the
                        plug-in, you do not need to run as administrator in
                        the normal course of your work. However, to install
                        any future updates will require running as
                        administrator. </para></entry>
                      </row>
                    </tbody>
                  </tgroup>
                </informaltable></para>
            </listitem>
          </itemizedlist></para>
      </sect2>

      <sect2>
        <title>Linux Prerequisites:</title>

        <para><itemizedlist>
            <listitem>
              <para>The HPCC Client Tools (available from <ulink
              url="http://hpccsystems.com/download/free-community-edition/client-tools">http://hpccsystems.com/download/free-community-edition/client-tools</ulink>
              )</para>

              <para>This installs the ECL compiler, eclcc, command line tools,
              and related components</para>
            </listitem>

            <listitem>
              <para>The Graph Control (available from <ulink
              url="http://hpccsystems.com/download/free-community-edition/graph-control">http://hpccsystems.com/download/free-community-edition/graph-control</ulink>)</para>
            </listitem>

            <listitem>
              <para>64-bit desktop edition of Linux</para>
            </listitem>

            <listitem>
              <para>Eclipse Indigo or later</para>
            </listitem>

            <listitem>
              <para>The ECL plug-in for Eclipse</para>
            </listitem>
          </itemizedlist></para>
      </sect2>

      <sect2 role="brk">
        <title>Mac (Intel-based) Prerequisites:</title>

        <itemizedlist>
          <listitem>
            <para>The HPCC Client Tools (available from <ulink
            url="http://hpccsystems.com/download/free-community-edition/client-tools">http://hpccsystems.com/download/free-community-edition/client-tools</ulink>
            )</para>

            <para>This installs the ECL compiler, eclcc, command line tools,
            and related components</para>
          </listitem>

          <listitem>
            <para>The Graph Control (available from <ulink
            url="http://hpccsystems.com/download/free-community-edition/graph-control">http://hpccsystems.com/download/free-community-edition/graph-control</ulink>)</para>
          </listitem>

          <listitem>
            <para>Mac OS X 64-bit (10.6.x or later)</para>
          </listitem>

          <listitem>
            <para>Eclipse Indigo or later</para>
          </listitem>

          <listitem>
            <para>The ECL plug-in for Eclipse</para>
          </listitem>
        </itemizedlist>
      </sect2>
    </sect1>
  </chapter>

  <chapter id="Installing_Eclipse">
    <title>Installing Eclipse</title>

    <para>This section describes how to install the Eclipse IDE. If you
    already have the Eclipse IDE installed, skip this section and go to
    <emphasis>Installing the ECL Plug-In</emphasis>.</para>

    <sect1 id="Used_to_Build_Queries" role="nobrk">
      <title>Getting Eclipse</title>

      <para>Download the Eclipse IDE from the site:</para>

      <para><ulink
      url="http://www.eclipse.org/downloads/">http://www.eclipse.org/downloads/</ulink>
      <itemizedlist>
          <listitem>
            <para>Choose the Eclipse IDE for Java Developers package</para>
          </listitem>

          <listitem>
            <para>Download the appropriate Eclipse IDE for your
            platform</para>
          </listitem>

          <listitem>
            <para>The Eclipse IDE is delivered as a compressed (.zip or
            .tar.gz) file. Extract this file into the folder of your choice
            (for example, c:\Eclipse on Windows).</para>
          </listitem>

          <listitem>
            <para>You can optionally create a shortcut to the executable file
            (<emphasis role="bold">eclipse.exe</emphasis> on Windows, or
            <emphasis role="bold">eclipse</emphasis> on Linux).</para>
          </listitem>
        </itemizedlist></para>
    </sect1>

    <sect1 id="Configuration_Files">
      <title>Installing the ECL Plug-in</title>

      <para>To install the Eclipse plug-in:</para>

      <para><orderedlist>
          <listitem>
            <para>In Eclipse IDE, select <emphasis role="bold">Help &gt;&gt;
            Install New Software…</emphasis></para>
          </listitem>

          <listitem>
            <para>Press the <emphasis role="bold">Add</emphasis>
            button.<figure>
                <title>Install Software: Add</title>

                <mediaobject>
                  <imageobject>
                    <imagedata fileref="images/EPI003.jpg" />
                  </imageobject>
                </mediaobject>
              </figure></para>
          </listitem>

          <listitem>
            <?dbfo keep-together="always"?>

            <para>Provide a suitable name, for example, <emphasis
            role="bluebold">ECL_PlugIn.</emphasis></para>
          </listitem>

          <listitem>
            <para>Enter one of the locations below in the <emphasis
            role="bold">Location</emphasis> field.</para>

            <para><variablelist>
                <varlistentry>
                  <term>Note:</term>

                  <listitem>
                    <para>We recommend the latest stable build for production
                    work.</para>
                  </listitem>
                </varlistentry>
              </variablelist></para>

            <para><informaltable colsep="1" frame="all" rowsep="1">
                <tgroup cols="2">
                  <colspec colwidth="310 pt" />

                  <colspec colwidth="255.0pt" />

                  <tbody>
                    <row>
                      <entry>http://eclipse.hpccsystems.com/stable</entry>

                      <entry>The latest stable build.</entry>
                    </row>

                    <row>
                      <entry>http://eclipse.hpccsystems.com/develop</entry>

                      <entry>The cutting-edge, untested development
                      build.</entry>
                    </row>
                  </tbody>
                </tgroup>
              </informaltable><figure>
                <title>Enter Location</title>

                <mediaobject>
                  <imageobject>
                    <imagedata fileref="images/EPI004.jpg" />

                    <!--This screen should show completed Location in the future-->
                  </imageobject>
                </mediaobject>
              </figure></para>
          </listitem>

          <listitem>
            <?dbfo keep-together="always"?>

            <para>Select the <emphasis role="bold">ECL Language</emphasis> box
            then press the <emphasis role="bold">Next &gt;</emphasis>
            button.</para>

            <variablelist>
              <varlistentry>
                <term>Note:</term>

                <listitem>
                  <para>This can take a while before it appears.</para>
                </listitem>
              </varlistentry>
            </variablelist>

            <para><figure>
                <title>Select ECL Language</title>

                <mediaobject>
                  <imageobject>
                    <imagedata fileref="images/EPI006.jpg" scale="80" />
                  </imageobject>
                </mediaobject>
              </figure></para>
          </listitem>

          <listitem>
            <para>Review the items to be installed and press the <emphasis
            role="bold">Next &gt;</emphasis> button.</para>
          </listitem>

          <listitem>
            <para>Accept the licensing agreement, then press the <emphasis
            role="bold">Finish</emphasis> button to complete the installation
            wizard.</para>
          </listitem>

          <listitem>
            <para>After completing the wizard, it prompts you to restart
            eclipse. You should restart eclipse in order for the changes to
            take effect.</para>
          </listitem>
        </orderedlist></para>
    </sect1>

    <sect1>
      <title>Updating the ECL Plug-in for Eclipse</title>

      <para>We recommend using the Eclipse Automatic Update feature.</para>

      <para><orderedlist>
          <listitem>
            <para>In Eclipse IDE, select <emphasis role="bold">Window &gt;&gt;
            Preferences.</emphasis></para>
          </listitem>

          <listitem>
            <para>Expand the <emphasis role="bold">Install/Update</emphasis>
            branch on the left, then select <emphasis role="bold">Automatic
            Updates</emphasis>.</para>

            <para>Check the <emphasis role="bold">Automatically find new
            updates and notify me</emphasis> button.</para>

            <figure>
              <title>Automatic Update Settings</title>

              <mediaobject>
                <imageobject>
                  <imagedata fileref="images/EPI017.jpg" scale="80" />
                </imageobject>
              </mediaobject>
            </figure>
          </listitem>

          <listitem>
            <para>Set your options, then press the<emphasis role="bold">
            OK</emphasis> button.</para>
          </listitem>
        </orderedlist>To manually update the Eclipse plug-in:</para>

      <para><orderedlist>
          <listitem>
            <para>In Eclipse IDE, select <emphasis role="bold">Help &gt;&gt;
            Check for Updates…</emphasis></para>

            <para>A progress window displays as it checks for any available
            updates.<emphasis role="bold"></emphasis></para>
          </listitem>

          <listitem>
            <para>If an update is available, follow the prompts to install
            it.</para>

            <para></para>
          </listitem>
        </orderedlist></para>
    </sect1>
  </chapter>

  <chapter id="Create_ECL_Project" role="brk">
    <title>Using Eclipse with HPCC</title>

    <para>The following sections tell you how you can use Eclipse to interact
    with the HPCC Platform.</para>

    <sect1 role="nobrk">
      <title>Creating an ECL Project</title>

      <para>In order to use Eclipse with an HPCC Platform, you will need to be
      able to create, edit, and submit ECL projects. This is how to do that
      with a simple "Hello World" project.</para>

      <para><orderedlist>
          <listitem>
            <para>Open the Eclipse IDE</para>
          </listitem>

          <listitem>
            <para>From the Workbench File menu, select <emphasis
            role="bold">File <emphasis role="bold">&gt;&gt;</emphasis> New
            <emphasis role="bold">&gt;&gt;</emphasis> Project…
            </emphasis></para>

            <para>This launches a <emphasis role="bold">New Project</emphasis>
            window which prompts you to Select a wizard</para>

            <para><graphic fileref="images/EPI007.jpg" scale="90" /></para>
          </listitem>

          <listitem>
            <para>Expand the <emphasis role="bold">ECL</emphasis> folder,
            select <emphasis role="bold">ECL Project</emphasis>, then press
            the <emphasis role="bold">Next</emphasis> button.</para>

            <graphic fileref="images/EPI007a.jpg" scale="90" />
          </listitem>

          <listitem>
            <para>In the <emphasis role="bold">Project</emphasis> window, give
            it an appropriate name. For example, <emphasis
            role="bluebold">hello_world.</emphasis></para>
          </listitem>

          <listitem>
            <para>Press the <emphasis role="bold">Finish</emphasis>
            button.</para>
          </listitem>

          <listitem>
            <?dbfo keep-together="always"?>

            <para>If your ECL Development perspective is not already open, you
            are prompted to <emphasis role="bold">Open Associated
            Perspective?</emphasis> Press the <emphasis
            role="bold">Yes</emphasis> button.</para>

            <para><graphic fileref="images/EPI008.jpg" /><variablelist>
                <varlistentry>
                  <term>Tip:</term>

                  <listitem>
                    <para>If you check the <emphasis role="bold">Remember my
                    decision checkbox</emphasis>, you won't have to do this
                    every time.</para>
                  </listitem>
                </varlistentry>
              </variablelist></para>
          </listitem>

          <listitem>
            <para>In the <emphasis role="bold">ECL Explorer</emphasis> panel,
            right-click on the newly created project, then select <emphasis
            role="bold">New <emphasis role="bold">&gt;&gt;</emphasis>
            File.</emphasis></para>

            <graphic fileref="images/EPI009.jpg" />

            <para>The <emphasis role="bold">New File</emphasis> window
            displays.</para>
          </listitem>

          <listitem>
            <?dbfo keep-together="always"?>

            <para>If necessary, select the parent folder, then provide a name
            for the file. For example, <emphasis
            role="bluebold">hello.ecl</emphasis>.</para>

            <para><graphic fileref="images/EPI0091a.jpg" /></para>

            <para><informaltable colsep="1" frame="all" rowsep="1">
                <?dbfo keep-together="always"?>

                <tgroup cols="2">
                  <colspec colwidth="49.50pt" />

                  <colspec />

                  <tbody>
                    <row>
                      <entry><inlinegraphic
                      fileref="images/caution.png" /></entry>

                      <entry>No matter what you name your file, be sure you
                      ALWAYS include the .ecl extension. The extension is
                      required for the project to work correctly with the HPCC
                      compiler.</entry>
                    </row>
                  </tbody>
                </tgroup>
              </informaltable></para>
          </listitem>

          <listitem>
            <?dbfo keep-together="always"?>

            <para>Add the following code (including the quotes):
            <programlisting>OUTPUT('Hello world'); </programlisting><graphic
            fileref="images/EPI010a.jpg" /></para>
          </listitem>

          <listitem>
            <para>Save your code by pressing the <emphasis
            role="bold">Save</emphasis> button on the toolbar, or selecting
            the <emphasis role="bold">File &gt;&gt; Save</emphasis> from the
            menu.</para>

            <informaltable colsep="1" frame="all" rowsep="1">
              <?dbfo keep-together="always"?>

              <tgroup cols="2">
                <colspec colwidth="49.50pt" />

                <colspec />

                <tbody>
                  <row>
                    <entry><inlinegraphic
                    fileref="images/OSSgr3.png" /></entry>

                    <entry>Saving an ECL file automatically invokes a syntax
                    check. If there is an error, it is indicated by a red X
                    next to the line containing the error.</entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
          </listitem>
        </orderedlist></para>
    </sect1>

    <sect1 id="Editing" role="brk">
      <title>Execute the ECL Code</title>

      <para>You can choose where to execute your ECL Code. Each target is
      defined in a <emphasis role="bold">Run Configuration</emphasis>.</para>

      <sect2>
        <title>Execute your ECL Code Remotely on a Server.</title>

        <orderedlist>
          <listitem>
            <para>Expand your project (hello_world), then rt-click on
            hello.ecl, and select <emphasis role="bold">Run As</emphasis>
            <emphasis role="bold">&gt;&gt;</emphasis> <emphasis
            role="bold">Run Configurations…</emphasis></para>

            <para><graphic fileref="images/EPI011.jpg" scale="80" /></para>
          </listitem>

          <listitem>
            <?dbfo keep-together="always"?>

            <para>Double click <emphasis role="bold">ECL Targets </emphasis>to
            create a new <emphasis role="bold">Run As</emphasis>
            configuration. <graphic fileref="images/EPI012a.jpg"
            scale="80" /></para>
          </listitem>

          <listitem>
            <?dbfo keep-together="always"?>

            <para>On the <emphasis role="bold">HPCC Platfom</emphasis> tab
            enter the following:<variablelist>
                <varlistentry>
                  <term>Name</term>

                  <listitem>
                    <para>Give it an appropriate name, for example: <emphasis
                    role="bold">ThorCluster</emphasis></para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term>IP address</term>

                  <listitem>
                    <para>IP address or DNS name of your ESP server</para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term>Port</term>

                  <listitem>
                    <para>The port to use (default is 8010)</para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term>Target name</term>

                  <listitem>
                    <para>The name of the cluster (for example, hthor, thor,
                    or roxie)</para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term>Credentials</term>

                  <listitem>
                    <para>Optional Username and Password to use (required if
                    security is enabled on the cluster)</para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term>ECL Watch / Address</term>

                  <listitem>
                    <para>This is autofilled from the Server IP Address above;
                    however, if your ECL Watch service is running on a
                    different IP or port, you can modify it here.</para>

                    <variablelist>
                      <varlistentry>
                        <term>Tip:</term>

                        <listitem>
                          <para>Press the test button and you will see its
                          current ECL Watch page. This lets you know you have
                          the correct configuration.</para>
                        </listitem>
                      </varlistentry>
                    </variablelist>
                  </listitem>
                </varlistentry>
              </variablelist></para>

            <figure>
              <title>Correct Configuration</title>

              <mediaobject>
                <imageobject>
                  <imagedata fileref="images/EPI013.jpg" scale="75" />
                </imageobject>
              </mediaobject>
            </figure>
          </listitem>

          <listitem>
            <?dbfo keep-together="always"?>

            <para>On the <emphasis role="bold">ECLCC Compiler</emphasis> tab
            check the settings. The location of your installed Client Tools
            should have been found and auto-completed. If they are not
            correct, check the Override Defaults box and fill in the location
            of your Client Tools.</para>
          </listitem>

          <listitem>
            <para>Press the <emphasis role="bold">Apply</emphasis> button to
            save your configuration.</para>
          </listitem>

          <listitem>
            <para>Press the <emphasis role="bold">Run</emphasis>
            button.</para>
          </listitem>

          <listitem>
            <?dbfo keep-together="always"?>

            <para>In the <emphasis role="bold">Workunits</emphasis> panel on
            the left, click and expand the <emphasis
            role="bold">Workunit</emphasis>, then click and expand the
            <emphasis role="bold">Outputs</emphasis> folder.</para>

            <para>The result(s) display in the center panel. (If your query
            has multiple results, then each result displays in a separate
            tab.)</para>

            <para><graphic fileref="images/EPI014.jpg" /></para>
          </listitem>

          <listitem>
            <para>Later you can use the drop list on the toolbar button to run
            on an established <emphasis role="bold">Run
            Configuration</emphasis>, as show below.</para>

            <graphic fileref="images/EPI018.jpg" />
          </listitem>
        </orderedlist>
      </sect2>
    </sect1>
  </chapter>

  <chapter>
    <title>Next Steps</title>

    <para>To familiarize yourself with the Eclipse IDE and the ECL Development
    perspective, we recommend working the following tutorials in Eclipse:
    <itemizedlist spacing="compact">
        <listitem>
          <para>The <emphasis role="bold">HPCC Data Tutorial</emphasis></para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">The Six Degrees of Kevin
          Bacon</emphasis> example</para>
        </listitem>
      </itemizedlist>To discuss this plug-in or get help using it, visit the
    forum on the HPCC System's portal at:</para>

    <para><ulink
    url="http://hpccsystems.com/bb/viewforum.php?f=33&amp;sid=adddbd537294bf32e2c46c1d7d16134e">http://hpccsystems.com/bb/viewforum.php?f=33&amp;sid=adddbd537294bf32e2c46c1d7d16134e</ulink></para>
  </chapter>
</book>