Difference between revisions of "ApCoCoA-1:HowTo:Install and Work with the Eclipse GUI"

From ApCoCoAWiki
m (Bot: Replacing category HowTo with HowTo Old)
 
(28 intermediate revisions by 11 users not shown)
Line 1: Line 1:
 
==Introduction==
 
==Introduction==
  
This HowTo shows you how to get started with the new Eclipse Graphical User Interface (GUI) for (Ap)CoCoA.
+
This HowTo shows you how to get started with the new Eclipse Graphical User Interface (GUI) for (Ap)CoCoA.  
  
Currently, the new GUI is still in an alpha state, which means there might be annoying bugs or the look and feel will change in the near future with new releases.
+
'''Edit June 2016:'''
 
+
'''Please note that there are compatibility problems with Eclipse versions 3.7 and newer. Since Eclipse 3.6 or older versions are no longer supported with updates, we recommend to use the Standalone Versions of (Ap)CoCoA until the compatibility problems have been fixed.'''
If this doesn't frighten you, you are more than welcome to
 
 
 
* follow the steps below and install the new GUI
 
* find and [http://www.apcocoa.org/bugtracker/ report any bugs]
 
* [http://www.apcocoa.org/bugtracker/ request any feature you miss]
 
* even contribute by developing new features yourself.
 
  
 
==Prerequisites==
 
==Prerequisites==
  
* A current [http://www.java.com/ Java runtime environment] (Java 5 JRE recommended)
+
* A current [http://www.java.com/ Java runtime environment]
 
* [http://www.eclipse.org/downloads/ Eclipse] If you are new to Eclipse, the variety of different packages to choose from may be confusing. However, for using ApCoCoA it does not matter which package you choose and we therefore recommend to choose the smallest one (which currently is the ''Eclipse IDE for C/C++ Developers'')
 
* [http://www.eclipse.org/downloads/ Eclipse] If you are new to Eclipse, the variety of different packages to choose from may be confusing. However, for using ApCoCoA it does not matter which package you choose and we therefore recommend to choose the smallest one (which currently is the ''Eclipse IDE for C/C++ Developers'')
* [http://www.apcocoa.org/wiki?title=ApCoCoA:Downloads ApCoCoA]
+
 
 +
  'Note' In order to benefit from the possibilities offered by the Eclipse update mechanism, we highly recommend to switch to Eclipse Galileo or later.
  
 +
  If you are using Eclipse 3.7 (Indigo) make sure to contact only the ApCoCoA update site, as described below!
  
 +
* [http://www.apcocoa.org/wiki?title=ApCoCoA:Downloads ApCoCoA]
  
 
==Installation==
 
==Installation==
Line 25: Line 22:
 
You will next be asked to provide a ''workspace directory''. This is where all your projects and (ApCoCoA) files will be stored. If unsure, just take the suggested directory.
 
You will next be asked to provide a ''workspace directory''. This is where all your projects and (ApCoCoA) files will be stored. If unsure, just take the suggested directory.
 
When you start Eclipse for the first time, you are presented with the welcome screen, which you can just close.
 
When you start Eclipse for the first time, you are presented with the welcome screen, which you can just close.
[[Image:01_welcome.png|thumb|none|150px]]
+
[[Image:01_welcome.png|thumb|none|800px]]
 
If you have downloaded the ''Eclipse IDE for C/C++ Developers'', Eclipse is in the ''C/C++ perspective'' (a perspective defines the arrangement of the different visual elements such as the editor, navigators,...) which is the starting point for this tutorial.
 
If you have downloaded the ''Eclipse IDE for C/C++ Developers'', Eclipse is in the ''C/C++ perspective'' (a perspective defines the arrangement of the different visual elements such as the editor, navigators,...) which is the starting point for this tutorial.
[[Image:02_start_eclipse.png|thumb|none|150px]]
+
[[Image:02_start_eclipse.png|thumb|none|800px]]
  
 
===Installing the Plugin===
 
===Installing the Plugin===
Line 33: Line 30:
 
* In the menu bar, click <code>Help > Install New Software...</code>
 
* In the menu bar, click <code>Help > Install New Software...</code>
 
* Next, enter at ''Work with:'' the URL <code>http://www.apcocoa.org/updatesite/</code> and click ''Add...''
 
* Next, enter at ''Work with:'' the URL <code>http://www.apcocoa.org/updatesite/</code> and click ''Add...''
* Just click ''Ok'' on the dialog that opens now.
+
* Just click ''Ok'' on the dialog that opens now, a name is optional for your new update site.
* Now you should see the following picture on your screen. [[Image:03_install_dialog.png|thumb|none|150px]]
+
* Now you should see the following picture on your screen. [[Image:03_install_dialog.png|thumb|none|800px]]
* Note: Maybe you have to uncheck ''Group items by category'' to see the Apcocoa GUI package.
+
* Then check Apcocoa GUI and the feature appropiate to your platform (e.g. Linux 32-Bit). Click <code>Next></code>.  
* Then check Apcocoa GUI and click <code>Next></code>.  
+
  NOTE: With the combination Eclipse 3.7 (Indigo) + ApCoCoA 1.7 and before, disable "Contact all updatesites ..."!
* Eclipse then looks up the plugins that have to be installed and presents you with a review and confirm page. Click <code>Next></code>.[[Image:04_review_dialog.png|thumb|none|150px]]
+
* Eclipse then looks up the plugins that have to be installed and presents you a review and confirm page. Click <code>Next></code>.[[Image:04_review_dialog.png|thumb|none|800px]]
* Accept the license agreement and click <code>Finish</code>.[[Image:05_accept_license.png|thumb|none|150px]]
+
* Accept the license agreement and click <code>Finish</code>.[[Image:05_accept_license.png|thumb|none|800px]]
 
* Next you will be asked to restart the Eclipse platform which is recommended.
 
* Next you will be asked to restart the Eclipse platform which is recommended.
 
* Finally, you should see some new additions in the menu and tool bars.<br/><br/>[[Image:New_Additions.jpg]]
 
* Finally, you should see some new additions in the menu and tool bars.<br/><br/>[[Image:New_Additions.jpg]]
Line 52: Line 49:
  
 
* Go to <code>Window > Preferences > ApCoCoA Preferences</code>
 
* Go to <code>Window > Preferences > ApCoCoA Preferences</code>
* Set paths to the ApCoCoA command line executable and ApCoCoA Server or BBF Server and click <code>OK</code> [[Image:06_setting_apcocoa_paths.png|thumb|none|150px]]
+
* Set paths to the ApCoCoA command line executable and ApCoCoA Server or BBF Server and click <code>OK</code> [[Image:06_setting_apcocoa_paths.png|thumb|none|800px]]
* Verify the settings by starting ApCoCoA, clicking on the ''(Re)start ApCoCoA Process'' button [[Image:ApCoCoA_Restart_Button.jpg]]. In the console view you can see now the ApCoCoA greeting message.<br/>[[Image:Greeting_Message.jpg|thumb|none|150px]]
+
* Verify the settings by starting ApCoCoA, clicking on the ''(Re)start ApCoCoA Process'' button [[Image:ApCoCoA_Restart_Button.jpg]]. In the console view you can see now the ApCoCoA greeting message.<br/>[[Image:Greeting_Message.jpg|thumb|none|800px]]
  
 
===Create a new Project===
 
===Create a new Project===
  
 
All work done within Eclipse is organized into projects. To create a new project
 
All work done within Eclipse is organized into projects. To create a new project
* Go to <code>File > New > Project ...</code><br/>[[Image:New_Project_Wizard.jpg|thumb|none|150px]]
+
* Go to <code>File > New > Project ...</code><br/>[[Image:07_apcocoa_project.png|thumb|none|800px]]
* In the Project Wizard, select <code>Project</code> in the <code>General</code> category and click <code>Next</code>.
+
* In the Project Wizard, select <code>ApCoCoA Project</code> in the <code>Other</code> category and click <code>Next</code>.
* Name the project ''GUI Tutorial'' and click <code>Finish</code>. [[Image:New_Project_Name.jpg|thumb|none|150px]]
+
* Name the project ''GUI Tutorial'' and click <code>Finish</code>. [[Image:New_Project_Name.jpg|thumb|none|800px]]
* In the Project Explorer on the left side you can now see the newly created project, moreover, Eclipse created a new folder in the workspace directory.<br/>[[Image:Project_Explorer.jpg|thumb|none|150px]]
+
* If you are not already in the ''ApCoCoA Perspective'', Eclipse asks you now if you want to switch to it. Accept this.
 +
* In the Navigator on the left side you can now see the newly created project, moreover, Eclipse created a new folder in the workspace directory.<br/>[[Image:08_eclipse_navigator.png|thumb|none|800px]]
  
 
===Create and use an (interactive) Editor Window===
 
===Create and use an (interactive) Editor Window===
  
To enter (Ap)CoCoA commands and programs, you need an editor window. Within the (Ap)CoCoA QT-GUI, there are two kinds of editor windows or, more specific, editor tabs: a) the interactive default editor tab, where you enter commands but usually do not edit programs (since the window is cleared after sending its content to (Ap)CoCoA); and (b) the "persistent" editor tabs, where you edit your programs. The interactive behavior is mimicked in Eclipse if you create a special "file" with the name <code>interactive.aco</code>:
+
To enter (Ap)CoCoA commands and programs, you need an editor window. Within the (Ap)CoCoA QT-GUI, there are two kinds of editor windows or, more specific, editor tabs: a) the interactive default editor tab, where you enter commands but usually do not edit programs (since the window is cleared after sending its content to (Ap)CoCoA); and (b) the "persistent" editor tabs, where you edit your programs. The interactive behavior is mimicked in Eclipse if you create a special "file" with the extension <code>.aco</code>:
  
 
* Right-click on the ''GUI Tutorial'' project and select <code>New > File</code>.
 
* Right-click on the ''GUI Tutorial'' project and select <code>New > File</code>.
* Create a new file named <code>interactive.aco</code>, click <code>Finish</code>. [[Image:New_File_Interactive.jpg|thumb|none|150px]]
+
* Create a new file e.g. named <code>interactive.aco</code> and click <code>Finish</code>. [[Image:New_File_Interactive.jpg|thumb|none|800px]]
* Type a sample command in the new editor window and send it to ApCoCoA, typing <code>Ctrl+Enter</code>. [[Image:Hello_World.jpg|thumb|none|150px]]
+
* Type a sample command in the new editor window and send it to ApCoCoA, typing <code>Ctrl+Enter</code>. [[Image:Hello_World.jpg|thumb|none|800px]]
 
* The editor windows content is then added to the history and the editor is cleared. As in the CoCoA QT-GUI, you can navigate through the histroy with <code>Alt+Left</code> and <code>Alt+Right</code>.
 
* The editor windows content is then added to the history and the editor is cleared. As in the CoCoA QT-GUI, you can navigate through the histroy with <code>Alt+Left</code> and <code>Alt+Right</code>.
 
* Note that the content of interactive editors is not saved to disk!
 
* Note that the content of interactive editors is not saved to disk!
 
   Tip: If you are uncomfortable with the key bindings, you can simply change them in the General Preferences (<code>Window > Preferences > General > Keys</code>).
 
   Tip: If you are uncomfortable with the key bindings, you can simply change them in the General Preferences (<code>Window > Preferences > General > Keys</code>).
  
To create a "normal" editor window, create a file with the extension <code>.aco</code>. Files with this extension are associated to ApCoCoA editors with all their features (syntax coloring, sending content to the ApCoCoA process via <code>Enter+Enter</code>,...).
+
To create a "normal" editor window, create a file with the extension <code>.coc</code> or <code>.cpkg</code>. Files with this extension are associated to ApCoCoA editors with all their features (syntax coloring, sending content to the ApCoCoA process via <code>Enter+Enter</code>,...).
  
 
===Getting Help===
 
===Getting Help===
To access the ApCoCoA Help go to <code>Help > Help Contents</code>. On the left side you find the ApCoCoA Handbook.<br/>[[Image:ApCoCoA_Help.jpg|thumb|none|150px]]
+
To access the ApCoCoA Help go to <code>Help > Help Contents</code>. On the left side you find the ApCoCoA Handbook.<br/>[[Image:ApCoCoA_Help.jpg|thumb|none|800px]]
  
 
==Further Topics==
 
==Further Topics==
Line 85: Line 83:
  
 
Since there is initially only one console view that would be shared by both the server and the cocoa process it is more convenient to  
 
Since there is initially only one console view that would be shared by both the server and the cocoa process it is more convenient to  
* pin the ApCoCoA console<br/>[[Image:Console_Pin.jpg|thumb|none|150px]]
+
* pin the ApCoCoA console<br/>[[Image:Console_Pin.jpg|thumb|none|800px]]
* open a second console view<br/>[[Image:Open_Console_View.jpg|thumb|none|150px]]
+
* open a second console view<br/>[[Image:Open_Console_View.jpg|thumb|none|800px]]
 
* rearrange the two console views (see below).
 
* rearrange the two console views (see below).
  
 
===Adjust the Appearance===
 
===Adjust the Appearance===
 
In Eclipse, it is possible to rearrange the visual components in (almost) any way you like via drag & drop.<br/>
 
In Eclipse, it is possible to rearrange the visual components in (almost) any way you like via drag & drop.<br/>
[[Image:GUI_Rearrangement.jpg|thumb|none|150px]]
+
[[Image:GUI_Rearrangement.jpg|thumb|none|800px]]
 +
 
 +
===Known Issues===
 +
* If you update the Eclipse GUI to 0.1.2 you should recheck your preferences and make sure that the CoCoA Interpreter / ApCoCoA Server are the ones delivered from the updatesite.
  
[[Category:HowTo|{{PAGENAME}}]]
+
[[Category:HowTo Old]]

Latest revision as of 09:42, 29 October 2020

Introduction

This HowTo shows you how to get started with the new Eclipse Graphical User Interface (GUI) for (Ap)CoCoA.

Edit June 2016: Please note that there are compatibility problems with Eclipse versions 3.7 and newer. Since Eclipse 3.6 or older versions are no longer supported with updates, we recommend to use the Standalone Versions of (Ap)CoCoA until the compatibility problems have been fixed.

Prerequisites

  • A current Java runtime environment
  • Eclipse If you are new to Eclipse, the variety of different packages to choose from may be confusing. However, for using ApCoCoA it does not matter which package you choose and we therefore recommend to choose the smallest one (which currently is the Eclipse IDE for C/C++ Developers)
 'Note' In order to benefit from the possibilities offered by the Eclipse update mechanism, we highly recommend to switch to Eclipse Galileo or later.
 If you are using Eclipse 3.7 (Indigo) make sure to contact only the ApCoCoA update site, as described below!

Installation

Installing and Running Eclipse

After you have downloaded one of the Eclipse packages (e.g. the Eclipse IDE for C/C++ Developers), unpack the package, go to the newly created folder eclipse and start the eclipse executable. That's all. You will next be asked to provide a workspace directory. This is where all your projects and (ApCoCoA) files will be stored. If unsure, just take the suggested directory. When you start Eclipse for the first time, you are presented with the welcome screen, which you can just close.

01 welcome.png

If you have downloaded the Eclipse IDE for C/C++ Developers, Eclipse is in the C/C++ perspective (a perspective defines the arrangement of the different visual elements such as the editor, navigators,...) which is the starting point for this tutorial.

02 start eclipse.png

Installing the Plugin

One of the really nice things in Eclipse is the ease of installing and updating plugins, i.e. extensions of the Eclipse platform that add new features and functionality to Eclipse, just as the GUI plugin does. To install the ApCoCoA GUI plugin, follow these steps:

  • In the menu bar, click Help > Install New Software...
  • Next, enter at Work with: the URL http://www.apcocoa.org/updatesite/ and click Add...
  • Just click Ok on the dialog that opens now, a name is optional for your new update site.
  • Now you should see the following picture on your screen.
    03 install dialog.png
  • Then check Apcocoa GUI and the feature appropiate to your platform (e.g. Linux 32-Bit). Click Next>.
 NOTE: With the combination Eclipse 3.7 (Indigo) + ApCoCoA 1.7 and before, disable "Contact all updatesites ..."! 
  • Eclipse then looks up the plugins that have to be installed and presents you a review and confirm page. Click Next>.
    04 review dialog.png
  • Accept the license agreement and click Finish.
    05 accept license.png
  • Next you will be asked to restart the Eclipse platform which is recommended.
  • Finally, you should see some new additions in the menu and tool bars.

    New Additions.jpg


You are now ready to set up and use ApCoCoA with Eclipse.

First Steps

Configure Eclipse

In the current alpha release, neither ApCoCoA executables are not packed with the Eclipse plugin yet. The plugin does also not check for installed ApCoCoA executables. Therefore, the paths have to be configured manually as follows.

  • Go to Window > Preferences > ApCoCoA Preferences
  • Set paths to the ApCoCoA command line executable and ApCoCoA Server or BBF Server and click OK
    06 setting apcocoa paths.png
  • Verify the settings by starting ApCoCoA, clicking on the (Re)start ApCoCoA Process button ApCoCoA Restart Button.jpg. In the console view you can see now the ApCoCoA greeting message.
    Greeting Message.jpg

Create a new Project

All work done within Eclipse is organized into projects. To create a new project

  • Go to File > New > Project ...
    07 apcocoa project.png
  • In the Project Wizard, select ApCoCoA Project in the Other category and click Next.
  • Name the project GUI Tutorial and click Finish.
    New Project Name.jpg
  • If you are not already in the ApCoCoA Perspective, Eclipse asks you now if you want to switch to it. Accept this.
  • In the Navigator on the left side you can now see the newly created project, moreover, Eclipse created a new folder in the workspace directory.
    08 eclipse navigator.png

Create and use an (interactive) Editor Window

To enter (Ap)CoCoA commands and programs, you need an editor window. Within the (Ap)CoCoA QT-GUI, there are two kinds of editor windows or, more specific, editor tabs: a) the interactive default editor tab, where you enter commands but usually do not edit programs (since the window is cleared after sending its content to (Ap)CoCoA); and (b) the "persistent" editor tabs, where you edit your programs. The interactive behavior is mimicked in Eclipse if you create a special "file" with the extension .aco:

  • Right-click on the GUI Tutorial project and select New > File.
  • Create a new file e.g. named interactive.aco and click Finish.
    New File Interactive.jpg
  • Type a sample command in the new editor window and send it to ApCoCoA, typing Ctrl+Enter.
    Hello World.jpg
  • The editor windows content is then added to the history and the editor is cleared. As in the CoCoA QT-GUI, you can navigate through the histroy with Alt+Left and Alt+Right.
  • Note that the content of interactive editors is not saved to disk!
 Tip: If you are uncomfortable with the key bindings, you can simply change them in the General Preferences (Window > Preferences > General > Keys).

To create a "normal" editor window, create a file with the extension .coc or .cpkg. Files with this extension are associated to ApCoCoA editors with all their features (syntax coloring, sending content to the ApCoCoA process via Enter+Enter,...).

Getting Help

To access the ApCoCoA Help go to Help > Help Contents. On the left side you find the ApCoCoA Handbook.

ApCoCoA Help.jpg

Further Topics

Working with the ApCoCoA / BBF Server

To start the ApCoCoA Server, click on the button Start ApCoCoA Server Start ApCoCoA Server.jpg.

Since there is initially only one console view that would be shared by both the server and the cocoa process it is more convenient to

  • pin the ApCoCoA console
    Console Pin.jpg
  • open a second console view
    Open Console View.jpg
  • rearrange the two console views (see below).

Adjust the Appearance

In Eclipse, it is possible to rearrange the visual components in (almost) any way you like via drag & drop.

GUI Rearrangement.jpg

Known Issues

  • If you update the Eclipse GUI to 0.1.2 you should recheck your preferences and make sure that the CoCoA Interpreter / ApCoCoA Server are the ones delivered from the updatesite.