Changes between Version 2 and Version 3 of EclipseInterface

Timestamp:

Jan 21, 2015, 12:25:35 AM (10 years ago)

Author:

manualwiki

Comment:

--

EclipseInterface

@@ -1 @@
-[[PageOutline]]
-
-[http://http://erlide.org/ ErlIDE] is an Eclipse-based development
-environment, which aims to assist programming of large scale Erlang
-applications. In order to integrate RefactorErl into Eclipse, we are
-engaged in creating an Eclipse plugin based on ErlIDE, which can enable
-access to all the functionality provided by RefactorErl, whilst
-utilising ErlIDE features as well. A prototype of the Eclipse plugin is
-already available.
-
-= Installation =
-
-== Software requirements ==
- * The plugin is being developed and tested in [http://www.eclipse.org/ Eclipse 3.5.2]. (It likely works with newer versions as well.)
- * This user interface is built upon [http://erlide.org/ ErlIDE], therefore it is required to have it with Eclipse. Inasmuch as the main structure
-  of ErlIDE has been changed in its version
-  ''v0.11.6.201107010651'', it is necessary to get the latest version.
- * Finally, you can download the plugin itself from the RefactorErl homepage.
-
-== Deployment ==
-To install this plugin you need to download the source code from the
-home page of the [http://plc.inf.elte.hu/erlang/dl/ RefactorErl]. In
-order to generate the binaryes of the plugin you can compile it using
-'''''ant''''' or the compiler of Eclipse. Finally you have to copy the
-generated jar files into your Eclipse plugin directory. In Eclipse 3.5.x:
-{{{
-<user home>/.eclipse/org.eclipse.platform_3.5.0_155965261/plugin
-}}}
-
-== Compiling the plugin in Eclipse ==
-todo
-
-== Compile plugin using Ant ==
-todo
-
-== Configuration ==
-The plugin, in order to be able to access RefactorErl, has to be set
-up before the first usage. For the configuration dialog, go to
-'''Window / Preferences / RefactorErl'''.
-
- Start background process automatically::
-   If set, the plugin launches a new instance of the tool, otherwise an
-   already running RefactorErl process will be used.
- RefactorErl directory::
-   The installation directory of the tool.
- Working directory::
-   A temporary directory, used to store the configuration files of
-   RefactorErl. It is assumed to be a writable directory.
- Waiting time::
-   This parameter represents the waiting time (in seconds) after
-   starting RefactorErl process (has to be set to greater than 1). The
-   slower access is possible to Erlang nodes, the greater value is suggested.
- Synchronize workspace automatically then model changed::
-   If a source file has been changed, the extension automatically updates
-   its inner representation within the tool.
- Reset database before full synchronization::
-   Resets the database and erases its contents in the case of a full
-   synchronisation. The use of this feature is recommended for RefactorErl
-   developers only.
-  
-= Database management =
-The Eclipse extension supports every database management functionality
-that is available in the RefactorErl tool. These can be executed from
-the top menu:
- * Add file,
- * Drop file,
- * Reset database,
- * Load directory,
- * Undo (one step only).
-
-You can get a list of the database contents by clicking on
-'''RefactorErl / Files / Database contents'''. A new tab, called
-'''Database contents''' pops up showing the modules having been loaded
-into RefactorErl. Also, you can select and drop modules from the tool
-database, and you can open files for editing.
-
-
-= Executing refactoring transformations =
-todo
-
-= Executing semantic queries =
-todo
-
-= Clustering =
-
-The RefactorErl tool provides a feature for reorganising the structure
-of the software, called clustering. It determines semantic
-dependencies among the modules and functions and makes suggestion to
-the developer how to repartition the software: blocks of modules,
-headers etc. As the RefactorErl tool, the Eclipse plugin supports the
-clustering on different entities like functions or modules. Although
-the module clustering can be executed using both genetic and
-agglomerative algorithms, the function clustering supports only the
-former one.
-
-To execute a clustering algorithm, you should select either of them
-from the top menu (e.g: '''RefactorErl / Module / Genetic'''). Every
-clustering method has the same input window, where you can adjust the
-parameters of the algorithm. (It's the usage and the required
-parameters of the different methods are detailed in
-[wiki:ModuleFunctionClustering Clustering] section). When the calculation
-has been finished, a new window pops up with the results of the clustering
-algorithm.
+
+= Introduction
+Most services provided by RefactorErl are accessible from the Eclipse IDE after installing the RefactorErl plugin in Eclipse. In this guide, we also refer to this plugin as the //Eclipse interface//. 
+The following functionalities are available from the Eclipse interface:
+* [#db Database management]
+* [#sq Semantic queries]
+* [#ref Refactoring]
+* [#dep Dependency graph drawing]
+* [#dup Duplicated code analysis]
+* [#inv Code investigations]
+
+A short description for each functionality can be found at the beginning of the relevant sections. 
+
+While not required, it's recommended to install [http://www.erlide.org the Erlide plugin] in Eclipse. Erlide enhances features of the RefactorErl plugin and transforms Eclipse into a complete Erlang IDE.
+
+[=#install]
+= Installation
+== Quick summary
+1. Install the [#instdep dependencies].
+1. To [#pluginst install the RefactorErl plugin in Eclipse], click on the **Help > Install new software** buttons in the Eclipse menu, click **Add...** in the appearing window, and paste the following link in the **Location** text field of the window named **Add Repository**: http://plc.inf.elte.hu/erlang/dl/update/
+1. [#firsttime After the installation], navigate to the preference pages by clicking **Window > Preferences > RefactorErl**, and fill in the **RefactorErl Base Directory** field with the path to the base directory of a locally installed RefactorErl application. In case you would like to connect to a remotely located RefactorErl node instead, fill in the node address of this node in the **Server address** field.
+
+[=#instdep]
+== Dependencies
+* Java 8 JRE/JDK or newer.
+* Eclipse 4.4.0 Luna or newer.
+* RefactorErl 0.9.14.09 or newer. (Not needed in case a remote RefactorErl node is available.)
+* GraphViz (Optional. Needed for displaying dependency graphs in SVG.)
+{{{#!comment
+* GEF4/Zest 2.0 Eclipse plugin (Optional. Needed for drawing Zest graphical representations of dependency graphs)
+}}}
+* Erlide 0.29 or newer (Optional.)
+
+=== Java & Eclipse
+Please see the developers' site for instructions concerning the obtainment and installation of [https://www.oracle.com/java/ Java] and [https:/www.eclipse.org/ Eclipse].
+
+=== RefactorErl
+Detailed instructions for installing RefactorErl can be found on the [wiki:Install related wiki page]. Of the various dependencies listed in the guide, the RefactorErl plugin depends only on the RefactorErl base system. This means that if you do not intend to use other interfaces besides the Eclipse interface, you don't need to install any other dependencies (Yaws, Erlang Wx, ...) listed on the referenced wiki page apart from the base system.
+
+As a remainder, here are the steps you need to follow in order to install RefactorErl:
+1. Install Erlang from your system package manager, or from an installer provided by [https://www.erlang-solutions.com/downloads/download-erlang-otp Erlang Solutions], or you can build [http://www.erlang.org/download.html Erlang from source]. Prior to installation make sure that the version of the Erlang package to be installed is supported by RefactorErl.
+1. Download [https://plc.inf.elte.hu/erlang/ RefactorErl]. 
+1. Uncompress the archive to the directory where you want RefactorErl to reside. 
+1. Enter the `refactorerl-x.y.z.v` directory you just uncompressed (here `x.y.z.v` denotes a version number). 
+   Type the command `bin\referl -build tool` in a terminal window. 
+   Wait for the build process to finish. If the build ends with an error, please refer to the wiki page mentioned before.
+1. Test the tool by typing `bin\referl` in your terminal. If the build was succesful, an Erlang shell should appear. 
+
+You will have to supply the location of the refactorerl-x.y.z.v directory (where we typed in the commands) to the RefactorErl plugin after the plugin is installed into Eclipse.
+
+=== GraphViz
+Optional. GraphViz is used to draw SVG representations of dependency graphs. You will have to supply the location of the `dot` executable of an installed GraphViz application the first time you use the SVG drawing feature.
+
+Hint: On UNIX-like systems, you can use the `type -a dot` command to locate the `dot` executable on your system. 
+
+GraphViz can be obtained from the [http://www.graphviz.org developers' website] or presumably from the package manager of your local system.
+
+{{{#!comment
+=== GEF4/Zest 2.0
+Optional. Zest 2.0 is used to draw dynamically adjustable Zest representations of dependency graphs. 
+
+The up-to-date version of the Zest 2.0 Eclipse plugin can be obtained from the [https://wiki.eclipse.org/GEF/GEF4 developers' website].
+
+You can also download Zest 2.0 from the RefactorErl update site. Just select the **GEF4/Zest 2.0** entry besides the RefactorErl plugin entry in the list after you added the update site in Eclipse. See the [#pluginst relevant section] for more information.
+Please note, that the version hosted on the RefactorErl update site might not be up-to-date.
+}}}
+
+=== Erlide
+Optional.
+
+The up-to-date version of the Erlide Eclipse plugin can be obtained from the [http://www.erlide.org developers' website]. 
+
+You can also download Erlide from the RefactorErl update site. Just select the **Erlang language tools IDE** entry besides the RefactorErl plugin entry in the list after you added the update site in Eclipse. See the [#pluginst relevant section] for more information. 
+Please note, that the version hosted on the RefactorErl update site might not be up-to-date.
+
+[=#pluginst]
+== Installing the RefactorErl plugin in Eclipse
+
+The RefactorErl plugin can be installed in Eclipse via our update site. 
+
+First copy the following link on the clipboard (eg. Right click > Copy Link Location): http://plc.inf.elte.hu/erlang/dl/update/
+
+Open Eclipse and click on the **Help > Install new software** buttons in the Eclipse menu. 
+{{{
+#!comment 
+KÉP
+}}}
+
+Click **Add...** in the appearing window, and paste the link we just copied to the clipboard in the **Location** text field of the window named **Add Repository**. Click OK.
+{{{
+#!comment
+KÉP
+}}}
+
+In the original **Install** window select the RefactorErl group and a list should appear, containing the plugins available from the update site we specified in the last step. {{{
+#!comment 
+KÉP
+}}} 
+
+To install the RefactorErl plugin, select the **RefactorErl Eclipse UI** entry. 
+The list might contain additional entries for optional dependencies (Erlang language tools IDE {{{#!comment , GEF4/Zest 2.0}}}). Installing these plugins is not required, but it will enhance some features of the RefactorErl plugin. Please note, that the version of these dependencies hosted on the RefactorErl update site might not be up-to-date. 
+
+After clicking **Next** on this window, Eclipse will lead you through a series of simple steps before the installation. After the installation is finished, you will need to restart Eclipse.
+
+== Uninstalling the RefactorErl plugin
+The RefactorErl plugin can be uninstalled from Eclipse like most other Eclipse plugins. 
+1. Open Eclipse
+1. Click on **Help > Installation Details** 
+1. In the appearing window select the **RefactorErl Eclipse UI** entry. Click on the **Uninstall** button.
+
+[=#firsttime]
+== First time launch
+If the plugin installation was successful in the last step, an error message will appear the first time Eclipse is launched. This happens because we didn't set the path to RefactorErl yet. 
+{{{
+#!comment 
+KÉP
+}}}
+
+The RefactorErl plugin can automatically start a local RefactorErl application and connect to it. Please, see the corresponding section of this guide, if RefactorErl is not yet installed on your system.
+It is also possible to connect to a RefactorErl application running on a remote server. You do not need to install RefactorErl on your local system to do this.
+
+Navigate to the preference pages by clicking **Window > Preferences > RefactorErl**. 
+{{{
+#!comment 
+KÉP
+}}} 
+
+In case you would like to connect to a local RefactorErl application, fill in the **RefactorErl Base Directory** field with the path to the base directory of a locally installed RefactorErl application. 
+
+In case you would like to connect to a remotely located RefactorErl node instead, fill in the node address of this node in the **Server address** field.
+
+Click **OK**. Click **Yes** on the dialog inquiring wheter you want to reconnect to RefactorErl. If the connection was successful, a `Connected to RefactorErl` message will appear in the left side of the status bar at the bottom of the Eclipse window. 
+{{{
+#!comment 
+KÉP
+}}}
+
+Congratulations, now you can start using RefactorErl with the Eclipse interface!
+
+= Using the RefactorErl Eclipse interface
+This section will guide you through the most important interface features. While we include a basic description for each feature group, it may be neccessary for you to read the corresponding wiki pages for an in-depth understanding of the feature group in question. 
+
+If you open the RefactorErl perspective or the Erlang perspective (if Erlide is installed) inside Eclipse, a new menu button, with the text **RefactorErl** on it, will appear in the Eclipse top menu. Much of the features are accessible through the **RefactorErl** menu, and some features can be accessed in more than one way.
+
+For the rest of this guide we will assume that you have the RefactorErl or the Erlang perspective opened and one of these is the active perspective. As a reminder, perspectives can be opened via the **Window > Open Perspective > Other** button in the Eclipse top menu. 
+
+[=#db]
+== Database management
+The RefactorErl server uses an internal database to store syntactic and semantic information on the source code. RefactorErl provides most of its services with the use of this information. In order for RefactorErl to be able to analyse a source file, that source file must be added to the database. 
+
+See the [wiki:ManagingFiles wiki page about database management] for a more detailed description of database management in RefactorErl.
+
+Database management features available in the Eclipse interface include: 
+* Listing the source files in the database
+* Showing the contents of a source file 
+* Adding new source files or directories of source files 
+* Dropping source files or directories
+* Synchronizing the database with the (possibly modified) source files on the disk
+* Synchronizing the GUI and the database in case of connection errors or other irregularities
+* Appending values to the `appdata` and `include` environment variables 
+* Removing previously added values from the environment variables 
+* Resetting the database
+
+You can open a view containing the list of files, called the //Database view//, by clicking **RefactorErl > Database > Show Database** in the top menu. 
+
+{{{
+#!comment 
+KÉP
+}}}
+
+When you click in the //Database view// with the right mouse button, a context menu will appear, containing all database management features. Some of them, like the //drop// and //show// features, are dependent on the files or directories selected in the view.
+Most database management features (the ones not depending on file selection) are also available in the **RefactorErl > Database** menu.
+
+Source files can also be opened by double clicking on their name in the //Database view//.
+
+[=#sq]
+== Semantic queries
+RefactorErl provides a semantic query language as a straightforward way to query the information residing in the database. See the [wiki:SemanticQuery wiki page on semantic queries] for a detailed description of this feature.
+
+The RefactorErl plugin for Eclipse provides an interface to
+* write and execute semantic queries with autocompletion support,
+* show the results of the previously executed query,
+* show a history of preceding queries and their results.
+
+Before we examine the interface, we have to note the following distinction: A semantic query can be //global// or it can be //position based//. Position based queries start with the `@` character. 
+As an example `mod.funs` is a global query, because it returns all functions of all modules in the database. On the other hand `@fun.references` is a position based query, because it returns all references to the function specified by a position on the source file.
+
+You can execute a global query by writing your query in the textfield initially with the text `Semantic query` in the Eclipse toolbar and pressing the return key. 
+You can also execute global queries by clicking on **RefactorErl > Queries > Start query**. A dialog will appear, where you can type the global query.
+{{{
+#!comment 
+KÉP
+}}}
+
+To execute a position based query, open the source file where you want to start the query from, and click on the desired position in the text of the file with the right mouse button. In the appearing context menu, select **Run query from position**. A dialog will appear, where you can type a position based query (or even a global query).
+
+{{{
+#!comment 
+KÉP
+}}}
+
+After a successful query execution a view, called //Query result view// will appear with the results of your query. You can double click on a line of the result, and if it's possible, an editor tab will open with the file containing the content of that line, highlighting the content in question.
+
+The **RefactorErl > Queries > Show query history** button will open the //Query history view//. Double clicking on a query in the //Query history view// will show a results of this query in a //Query result view//. Please note, that these are historical results, it may or may not be consistent with the current content of the database.
+
+
+[=#ref]
+== Refactoring
+See the [wiki:RefactoringSteps wiki page about the available refactorings] for a detailed description of this feature.
+[=#dep]
+== Dependency graph drawing
+See the [wiki:Dependency wiki page about dependency analysis] for a detailed description of this feature.
+[=#dup]
+== Duplicated code analysis
+See the [wiki:CloneIdentifiErl wiki page about duplicated code analysis] for a detailed description of this feature.
+[=#inv]
+== Code investigations