Skip to content

Commit

Permalink
fixed documentation a bit
Browse files Browse the repository at this point in the history
  • Loading branch information
@JPMoresmau
JPMoresmau committed Feb 18, 2011
1 parent 222994d commit 3f440d2
Show file tree
Hide file tree
Showing 10 changed files with 423 additions and 404 deletions.
3 changes: 3 additions & 0 deletions docs/releasenotes/net.sf.eclipsefp.haskell_2.0.3.txt
View file
Expand Up @@ -23,6 +23,7 @@ Fixes:
- When launching GHCi, only hidden packages are added via -package
- When running a haskell file with the "launch the selected ressource or active editor", if an existing launch configuration exists, it it reused.
- When an existing launch configuration is found for a ressource, update executable to be the current executable for the delegate
- Documentation has been updated to not say things that are now totally wrong :-)

Features:
- Interface to cabal install via contextual action on project
Expand Down Expand Up @@ -60,6 +61,8 @@ Features:

- Occurrences shown in current files (based on lexer, so internal functions with the same name will be highlighted too)

- Set Cabal flags values in Project preferences.

Internal:

Upgrade notes:
Expand Down
340 changes: 162 additions & 178 deletions net.sf.eclipsefp.haskell.doc.user/html/gettingStarted.html
View file
@@ -1,178 +1,162 @@
<h2>A quick start guide to Haskell programming with Eclipse</h2>

<p>This document shows how you would create and run the 'Hello World'
application in Eclipse with Haskell support. It also explains some of the
main user interface elements in Eclipse. The focus is on helping
developers who are not familiar with Eclipse to quickly get started
with it as an IDE that supports Haskell development.</p>

<p>
<ul><li>
More information about how to use Eclipse can be found in the
<b>Workbench User Guide</b> which is included in the Eclipse
Help.
</li><li>
For more information about Haskell go to <a href="http://haskell.org">
http://haskell.org</a>.
</li><li>
Note that you need an installation of the Glasgow Haskell Compiler (GHC)
on your system. (See
<a href="http://haskell.org/ghc">http://haskell.org/ghc</a>.) If you don't,
you can still work with Haskell sources (and run them in HUGS), but you
won't see any syntax errors etc., and there will be no executable
automatically built from the sources.
</li></ul>
</p>

<p><b>Note:</b> This is work in progress, which means that some of the features
described here may not yet be in place.</p>

<h3><a name="preparations">Preparations</a></h3>

<ul>
<li><p><b>Open the Haskell Perspective</b>
<p>
Eclipse makes use of a concept called <b><i>Perspectives</i></b>.
Everything in the workspace is seen from such a Perspective. When you
start Eclipse for the first time, the most basic of all Perspectives is
open: the <i>Resource Perspective</i>, which handles just some basic
file management and text editing. By openening the Haskell perspective,
you activate everything that is Haskell-aware.
</p>
<ul><li><p>
Select from the menu: <b>Window &gt; Open Perspective &gt; Haskell</b>.
(You can also open the Haskell Perspective from a link on the
<b>Welcome</b> page.)
</p></li></ul>
<p>
Seen from the Haskell Perspective, a file is not just a file, but (if it
has the correct extension) a Haskell source file, which means that you
can open it with the Haskell source editor, you can compile it and run
it with a Haskell interpreter (like HUGS) or as (e.g. with GHC)
compiled and linked executable. The Perspective contains also some
<b><i>Views</i></b>, which provide Haskell-specific information about
the file which is currently opened in the editor (<b>Outline View</b>)
or about the last build process (in the <b>Console View</b>).
</p>
<p>
You can switch and close Perspectives at any time from the vertical
toolbar at the left of the workbench. If you have closed a Perspective
or a View, you can re-open it from the menu <b>Window &gt; Open
Perspective</b> or <b>Show View</b>.
</p>
</li>
<li><p><b><a name="haskellProject">Create a new Haskell project</a></b></p>
<p>
The workspace is organized into <i><b>Projects</b></i> (roughly:
directories within the workspace directory).
</p>

<ul><li><p>
Create a new project by selecting <b>File &gt; New &gt; Project</b> from
the menu, expanding the <b>Functional programming</b> icon, then choosing
<b>Haskell Project</b>. Specify a project name and hit <b>OK</b>.
</p></li></ul>

<p>
A Haskell project has some properties:
<ul>
<li><b>source folder</b> (where the compiler expects the sources)</li>
<li><b>output folder</b> (used by the compiler for object files)</li>
<li><b>binaries folder</b> (where the target executable is put)</li>
<li><b>target binary name</b> (the name of the executable produced
by the compiler and linker).</li>
</ul>
</p>
<p>
When the project has been created, you will see the respective folders,
which are created by the <b>New Project</b> wizard. You can configure
these settings on the <b>Preference Page</b> for that wizard.
</p>
</li>
</ul>

<h3><a name="createSource">Create and edit source files</a></h3>

<p>
Add source files to the project source folder.
</p>

<ul><li><p>
Files can be created either from the menu (<b>File &gt; New</b>), or from
the context menu you get when you right-click the project in the
<i>Project Explorer</i> View).
</p></li>

<li><p>
For the 'Hello world' program, create a new file named
<code>Main.hs</code>.
</p></li></ul>

<p>
If you give the files a Haskell-specific extension (like <code>.hs</code>
or <code>.lhs</code> (for literate Haskell), you can open the files with
the <i><b>Haskell source code editor</b></i> from the Project Explorer
view.</p>
</p>

<ul><li><p>
Right-click the file and choose <b>Open with &gt;Haskell editor</b>.
Type some code.
</p></li></ul>

<p>You can configure the editor in the main <i><b>Preferences Dialog</b></i>:
Select <b>Window &gt; Preferences</b> from the menu and choose the
<b>Functional Programming</b> section.</p>

<ul>
<li><p>
Enter the code for your 'Hello world', e.g.
<table width="50%"><tr><td bgcolor="#d0d0d0"><pre><code>
<b>module</b> Main <b>where</b>

main = putStr "Hello world!"
<code></pre><td><tr></table>
</p></li>

<li><p>
<b>Save</b>. This will trigger the auto building, and you will see compiler
errors (if there were errors in the build) in the <b><i>Problems
View</i></b>. If no errors have occured, the compiled object files and
the linked executable should be in their respective folders. Auto building
works incrementally, that is, only changed resources are built when you
save again.
</p></li>
</ul>

<h3><a name="run">Run the application</a></h3>

<p>
You can launch the compiled executable of your Haskell programs from within
the IDE.
</p>

<ul><li>
Select <b>Run As &gt; Haskell Application</b> from the menu <b>Run</b> (or
from the lauching icon that looks like a white triangle in a green circle).
You can also right-click the executable in the Project Explorer view
and choose <b>Run &gt; Haskell Application</b> from the popup menu.
</li></ul>

<p>
Running a program creates a new <b>Launch configuration</b> for that
program. You can re-run a lauch configuration from the <b>Run</b> menu.
Clicking the Run-icon re-launches always the last launched configuration.
</p>

<p>
If you choose <b>Run ...</b> from the menu, you get a dialog where you
can edit launch configurations. For example, you may want to add parameters
to the program launch.
</p>

<p>
Console input and output are handled by the <b>Console View</b> (at the
bottom left of the workbench). You should see the 'Hello world' output
appear there, and if your program takes console input, the Console View
is where you can type in while developing.
</p>
<h2>A quick start guide to Haskell programming with Eclipse</h2>

<p>This document shows how you would create and run the 'Hello World'
application in Eclipse with Haskell support. It also explains some of the
main user interface elements in Eclipse. The focus is on helping
developers who are not familiar with Eclipse to quickly get started
with it as an IDE that supports Haskell development.</p>

<p>
<ul><li>
More information about how to use Eclipse can be found in the
<b>Workbench User Guide</b> which is included in the Eclipse
Help.
</li><li>
For more information about Haskell go to <a href="http://haskell.org">
http://haskell.org</a>.
</li></ul>
</p>

<p><b>Note:</b> This is work in progress, which means that some of the features
described here may not yet be in place.</p>

<h3><a name="preparations">Preparations</a></h3>

<ul>
<li><p><b>Open the Haskell Perspective</b>
<p>
Eclipse makes use of a concept called <b><i>Perspectives</i></b>.
Everything in the workspace is seen from such a Perspective. When you
start Eclipse for the first time, the most basic of all Perspectives is
open: the <i>Resource Perspective</i>, which handles just some basic
file management and text editing. By openening the Haskell perspective,
you activate everything that is Haskell-aware.
</p>
<ul><li><p>
Select from the menu: <b>Window &gt; Open Perspective &gt; Haskell</b>.
(You can also open the Haskell Perspective from a link on the
<b>Welcome</b> page.)
</p></li></ul>
<p>
Seen from the Haskell Perspective, a file is not just a file, but (if it
has the correct extension) a Haskell source file, which means that you
can open it with the Haskell source editor, you can compile it and run
it with a Haskell interpreter (like HUGS) or as (e.g. with GHC)
compiled and linked executable. The Perspective contains also some
<b><i>Views</i></b>, which provide Haskell-specific information about
the file which is currently opened in the editor (<b>Outline View</b>)
or about the last build process (in the <b>Console View</b>).
</p>
<p>
You can switch and close Perspectives at any time from the vertical
toolbar at the left of the workbench. If you have closed a Perspective
or a View, you can re-open it from the menu <b>Window &gt; Open
Perspective</b> or <b>Show View</b>.
</p>
</li>
<li><p><b><a name="haskellProject">Create a new Haskell project</a></b></p>
<p>
The workspace is organized into <i><b>Projects</b></i> (roughly:
directories within the workspace directory).
</p>

<ul><li><p>
Create a new project by selecting <b>File &gt; New &gt; Project</b> from
the menu, expanding the <b>Haskell</b> icon, then choosing
<b>Haskell Project</b>. Specify a project name and hit <b>OK</b>.
</p></li>
<li><p>Specify a project name</p></li>
<li><p>Specify where you want the project to reside (default is inside your workspace</p></li>
<li><p>Specify some initial components to be created for you. The New Project wizard will auto generate a cabal file that will contain a reference to each component you select. You can choose to create an executable, a library, or both.</p></li>
</ul>
</li>
</ul>

<h3><a name="createSource">Create and edit source files</a></h3>

<p>
Add source files to the project source folder.
</p>

<p>If you have selected "executable" in the new project wizard page, a
<code>Main.hs</code> file should have been created for you.
Otherwise you can create a new Haskell module from the menu (<b>File &gt; New &gt; Haskell &gt; Haskell Module</b>).
The second page of the wizard lets you choose in which component the module will be present. You can have a project with several components, and not all modules are present in all components.
</p>

<p>
If you give the files a Haskell-specific extension (like <code>.hs</code>
or <code>.lhs</code> (for literate Haskell), you can open the files with
the <i><b>Haskell source code editor</b></i> from the Project Explorer
view.</p>
</p>

<ul><li><p>
Right-click the file and choose <b>Open with &gt;Haskell editor</b>.
Type some code.
</p></li></ul>

<p>You can configure the editor in the main <i><b>Preferences Dialog</b></i>:
Select <b>Window &gt; Preferences</b> from the menu and choose the
<b>General &gt; Editors &gt; Text Editors</b> section.</p>

<ul>
<li><p>
Enter the code for your 'Hello world', e.g.
<table width="50%"><tr><td bgcolor="#d0d0d0"><pre><code>
<b>module</b> Main <b>where</b>

main = putStr "Hello world!"
<code></pre><td><tr></table>
</p></li>

<li><p>
<b>Save</b>. This will trigger the auto building, and you will see compiler
errors (if there were errors in the build) in the <b><i>Problems
View</i></b>. If no errors have occurred, the compiled object files and
the linked executable should be in their respective folders. Auto building
works incrementally, that is, only changed resources are built when you
save again.
</p></li>
</ul>

<h3><a name="run">Run the application</a></h3>

<p>
You can launch the compiled executable of your Haskell programs from within
the IDE.
</p>

<ul><li>
Select <b>Run As &gt; Haskell Application</b> from the contexual <b>Run</b> menu on the project.
This is only available if your project contains executable modules and if it has been built by Scion.
</li></ul>

<p>
Running a program creates a new <b>Launch configuration</b> for that
program. You can re-run a lauch configuration from the <b>Run</b> menu.
Clicking the Run-icon re-launches always the last launched configuration.
</p>

<p>
If you choose <b>Run ...</b> from the menu, you get a dialog where you
can edit launch configurations. For example, you may want to add parameters
to the program launch.
</p>

<p>
Console input and output are handled by the <b>Console View</b> (at the
bottom left of the workbench). You should see the 'Hello world' output
appear there, and if your program takes console input, the Console View
is where you can type in while developing.
</p>

<h3><a name="run">Run a module in the interpreter</a></h3>

<p>You can right click on any Haskell module and choose <b>Run GHCi session</b>. This will open GHCi, the GHC interpreter, in a Eclipse console, and load all the required modules.</p>

<p>You can type in that console and have a full interactive session, modifying your modules in the Eclipse editors and running code in the console</p>

<p>The launch configuration options for interpreter sessions let you configure some automation features, like automatically reloading modules that you've saved in the editor.</p>


32 changes: 32 additions & 0 deletions net.sf.eclipsefp.haskell.doc.user/html/installation.html
View file
@@ -0,0 +1,32 @@
<h2>Installation steps</h2>
<p>If you see this, you have successfully installed the eclipseFP plugins.
However there may still be some configuration steps to be done before you can use the plugins fully.</p>

<h3>GHC configuration</h3>
<p>
EclipseFP requires GHC to compile Haskell source files.
We recommend installing the <a href="http://hackage.haskell.org/platform/">Haskell Platform</a> that comes with all required libraries bundled in a installer for your platform.
You can configure GHC by opening the Eclipse Preferences and going to <b>Haskell &gt; Haskell implementations</b>. If a GHC is in your PATH you should see it in the list. Otherwise you can manually add a GHC installation.
</p>

<h3>Cabal configuration</h3>
<p>
EclipseFP also requires a working Cabal. <a href="http://www.haskell.org/haskellwiki/Cabal">Cabal</a> is a build management tool for Haskell. Similarly, the Haskell Platform contains a version of Cabal compatible with the GHC it ships with.
You can configure Cabal in the Eclipse Preferences under <b>Haskell &gt; Scion and Cabal</b>. By default EclipseFP will have looked in your PATH and use any Cabal installation it can find there.
</p>

<h3>Scion configuration</h3>
<p>
Scion is a Haskell program that uses GHC and Cabal to give a consistent API to manage and build Haskell projects. EclipseFP uses Scion for a lot of operations.
It comes with a version of Scion in source form, that should get built automatically once GHC and Cabal have been set up.
The Eclipse Preferences page under <b>Haskell &gt; Scion and Cabal</b> allows you to change settings if required.
We recommend to stick to default setting (built-in server through Standard Stream/Pipe) unless you feel adventurous!
</p>

<h3>Problems building Scion</h3>
<p>
It may happen that Scion does not build successfully when you start EclipseFP.
The build process dumps its outputs and errors into a Console in the Console View of Eclipse. Please check this file for errors.
Often, the build fails due to some libraries conflict. Please run <b>cabal update</b> before restarting EclipseFP.
This will ensure your Cabal knows about the latest versions of libraries available on Hackage.
</p>

0 comments on commit 3f440d2

Please sign in to comment.