Document :stepover in ghci help
[ghc-hetmet.git] / docs / vh / vh.xml
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 ]>
5
6   <article id="visual-haskell">
7   
8     <articleinfo>
9
10       <title>Visual Haskell User's Guide</title>
11     <author>
12       <firstname>Simon</firstname>
13       <surname>Marlow</surname>
14       <email>simonmar@microsoft.com</email>
15     </author>
16     <author>
17       <firstname>Krasimir</firstname>
18       <surname>Angelov</surname>
19       <email>kr.angelov@gmail.com</email>
20     </author>
21
22 <!--
23     <abstract>
24       <para></para>
25     </abstract>
26 -->
27
28     </articleinfo>
29
30     <section id="sec-introduction">
31       <title>Introduction</title>
32       
33       <para>Visual Haskell is a plugin for Microsoft's Visual Studio
34         development environment to support development of Haskell software.
35         Like the other Visual languages, Visual Haskell integrates with the
36         Visual Studio editor to provide interactive features to aid Haskell
37         development, and it enables the construction of projects consisting of
38         multiple Haskell modules.</para>
39
40       <section id="sec-obtaining">
41         <title>Installing Visual Haskell</title>
42
43         <para>In order to use Visual Haskell, you need <ulink url="http://msdn.microsoft.com/vstudio/productinfo/">Visual Studio .NET
44           2003</ulink>.  Right now, this is the only supported version of Visual
45           Studio - unfortunately we haven't yet added support for the 2005
46           Beta.  The Express languages (Visual C++ Express etc.) also will not
47           work, because they don't have support for plugins.</para>
48
49         <para>You don't need to install GHC separately: Visual Haskell
50           is bundled with a complete GHC distribution, and various other tools
51           (Happy, Alex, Haddock).</para>
52
53         <para>The latest Visual Haskell installer can be obtained from
54           here:</para>
55
56         <para><ulink
57           url="http://www.haskell.org/visualhaskell/"><literal>http://www.haskell.org/visualhaskell/</literal></ulink></para>
58       </section>
59
60       <section id="release-notes">
61         <title>Release Notes</title>
62
63         <section>
64           <title>Version 0.0, first release</title>
65           
66           <para>This release is a technology preview, and should be considered
67             alpha quality.  It works for us, but you are fairly likely to
68             encounter problems.  If you're willing to try it out and report
69             bugs, we'd be grateful for the feedback.</para>
70
71           <itemizedlist>
72             <listitem>
73               <para>This release of Visual Haskell is bundled with a
74                 development snapshot of GHC, version 6.5 from around 14
75                 September 2005.  This version of GHC is used to provide the
76                 interactive editing features, and will be used to compile all
77                 code inside Visual Haskell.  It is possible that in future
78                 releases we may be able to relax this tight coupling between
79                 Visual Haskell and the bundled GHC.</para>
80
81               <para>Please note that future releases of Visual
82                 Haskell will update the compiler, and hence the
83                 packages, and so may break your code.  Also note that because
84                 the bundled GHC is not a released version, it may have bugs and
85                 quirks itself: please report them as usual to
86                 <email>glasgow-haskell-bugs@haskell.org</email>.</para>
87           </listitem>
88
89           <listitem>
90             <para>We're not making source code for the plugin generally
91               available at this time, due to licensing restrictions on the
92               Visual Studio APIs that the plugin uses (for more
93               information see <ulink
94                 url="http://msdn.microsoft.com/vstudio/extend/">Visual Studio
95                 Extensibility Center</ulink>).  If you're interested in
96               contributing to Visual Haskell, please get in touch with the
97               authors.</para>
98           </listitem>
99         </itemizedlist>
100       </section>
101     </section>
102
103       <section id="sec-bugs">
104         <title>Getting support, reporting bugs</title>
105         <para>Please report bugs to
106           <email>glasgow-haskell-bugs@haskell.org</email> (subscribe <ulink url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs">here</ulink>), clearly indicating
107           that your bug report relates to Visual Haskell, and giving as much
108           information as possible so that we can reproduce the bug.  Even if
109           you can't reproduce the bug reliably, it is still useful to report
110           what you've seen.</para>
111
112         <para>For help and support, use the
113           <email>glasgow-haskell-users@haskell.org</email> (subscribe <ulink
114             url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-users">here</ulink>) mailing list.</para>
115       </section>
116
117       <section id="sec-license">
118         <title>License</title>
119
120       <blockquote>
121         <para>Copyright © Microsoft Corporation. All rights reserved.</para>
122         <para>Copyright © The University of Glasgow. All rights reserved.</para>
123         <para>Copyright © Krasimir Angelov. All rights reserved.</para>
124
125         <para>Redistribution and use in source and binary forms, with or without
126           modification,  are permitted provided that the following conditions
127           are met:</para>
128
129         <itemizedlist>
130           <listitem>
131             <para>Redistributions of source code must retain the above
132               copyright notice, this list of conditions and the following
133               disclaimer.</para>
134           </listitem>
135  
136           <listitem>
137             <para>Redistributions in binary form must reproduce the above
138               copyright notice, this list of conditions and the following
139               disclaimer in the documentation and/or other materials provided
140               with the distribution.</para>
141           </listitem>
142
143           <listitem>
144             <para>The names of the copyright holders may not be used to endorse
145               or promote products derived from this software without specific
146               prior written permission.</para>
147           </listitem>
148         </itemizedlist>
149
150         <para>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS
151           "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
152           LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
153           FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
154           COPYRIGHT HOLDERS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
155           SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
156           LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
157           USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
158           AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
159           LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
160           ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
161           POSSIBILITY OF SUCH DAMAGE.</para>
162       </blockquote>
163     </section>
164
165     </section>
166
167     <section id="sec-using">
168       <title>Using Visual Haskell</title>
169
170       <section>
171         <title>Overview of features</title>
172
173         <para>The following features are provided in the Visual Studio editor
174           when editing Haskell code:</para>
175
176         <itemizedlist>
177           <listitem>
178             <para>Automatic checking of code as you type, and visual indication
179               of parse errors, scoping errors and type errors.</para>
180           </listitem>
181           
182           <listitem>
183           <para>Quick info: hovering the mouse over an identifier pops up
184             an information box, including the type of the identifier.</para>
185           </listitem>
186
187           <listitem>
188           <para>A drop-down bar at the top of the editing window lists the
189             top-level declarations in the module, and allows quick navigation
190             to a declaration.</para>
191           </listitem>
192
193           <listitem>
194           <para>Name completion for identifiers in scope: press Ctrl+Space
195             after a partial identifier to see the completions.</para>
196           </listitem>
197
198           <listitem>
199           <para>Go to declaration: right clicking on an identifier and
200             selecting "Go to declaration" will jump the cursor to the
201             declaration of the identifier.  This works for locally-defined
202             identifiers and those defined in another module of the project; it
203             does not work for library functions currently.</para>
204           </listitem>
205         </itemizedlist>
206
207       <para>The following features are provided by the project system for
208         constructing Haskell projects:</para>
209
210       <itemizedlist>
211         <listitem>
212           <para>Multi-module Haskell projects are fully supported, based on the
213             <ulink url="http://www.haskell.org/cabal">Cabal</ulink>
214             infrastructure.  A project in Visual Haskell <emphasis>is</emphasis>
215             a Cabal package, and vice-versa.  A Visual Studio project can be
216             taken to a machine without Visual Haskell and built/installed as a
217             normal Cabal package, and an existing Cabal package can be edited
218             directly in Visual Haskell<footnote><para>This works as long as the
219                 Cabal package is using Cabal's simple build system; Cabal
220                 packages using their own build systems cannot be edited in Visual
221                 Haskell.</para>
222             </footnote>.</para>
223         </listitem>
224
225         <listitem>
226           <para>Editing of most of the package meta-data is supported through
227             the project property pages.</para>
228         </listitem>
229
230         <listitem>
231           <para>The interactive editing features work across multiple modules in
232             a project.  When one module is edited, changes are automatically
233             propagated to dependent modules, even if the edited module has not yet
234             been saved.</para>
235         </listitem>
236
237         <listitem>
238           <para>Building is supported through the Cabal build system, and build
239             errors are communicated back to the editor and placed in the task
240             list.  Use any of the Visual Studio build commands (e.g. Build
241             Project from the context menu on the project, or Ctrl-Shift-B to
242             build the whole solution).</para>
243         </listitem>
244
245       </itemizedlist>
246     
247     <para>Additionally, Visual Haskell is bundled with a large collection of
248       documentation: the GHC manual, the hierarchical libraries reference, and
249       other material all of which can be browsed within Visual Studio
250       itself.</para>
251     </section>
252
253     <section>
254       <title>Getting Started</title>
255       
256       <para>After installing Visual Haskell, start up Visual Studio as you
257         would normally, and observe that on the splash screen where it lists
258         the supported languages you should now see an icon for Visual
259         Haskell (if you don't see this, something has gone wrong... please let
260         us know).</para>
261       
262       <para>Firstly, take a look at the bundled documentation.  Go to
263         Help-&gt;Contents, and you should see the &ldquo;Visual Haskell Help
264         Collection&rdquo;, which contains a large collection of GHC and
265         Haskell-related documentaiton, including this document.</para>
266
267       <para>To start using Visual Haskell right away, create a new
268         project (File-&gt;New-&gt;Project...).  Select one of the Haskell
269         project types (Console Application or Library Package), and hit Ok.
270         The project will be created for you, and an example module
271         added: <literal>Main.hs</literal> for an application, or
272         <literal>Module1.hs</literal> for a library.</para>
273       
274       <para>You can now start adding code to
275         <literal>Main.hs</literal>, or adding new modules.  To add a new
276         module, right-click on the <literal>src</literal> directory, and
277         select Add-&gt;New Item.  Visual Haskell supports hierarchical
278         modules too: you can add new folders using the same Add menu to
279         create new nodes in the hierarchy.</para>
280       
281       <para>If you have any errors in your code, they will be underlined with
282         a red squiggly line.  Select the Tasks window (usually a tab near the
283         bottom of the Visual Studio window) to see the error messages, and
284         click on an error message to jump to it in the editor.</para>
285       
286       <para>To build the program, hit Ctrl-Shift-B, or select one of the
287         options from the Build menu.</para>
288     </section>
289
290     <section>
291       <title>Editing Haskell code</title>
292
293         <para>(ToDo: more detail here)</para>
294
295         <para>Your module must be plain Haskell (<literal>.hs</literal>) for the interactive features to
296         fully work.  If your module is pre-processed with CPP or Literate
297           Haskell, then Visual Haskell will only check the module when it is
298           saved; between saves the source will not be checked for errors and
299           the type information will not be updated.  If the source file is
300           pre-processed with Happy or another pre-processor, then you may have
301           to build the project before the type information will be updated
302           (because the pre-processor is only run as part of the build
303           process).  Pre-processed source files work fine in a multi-module
304           setting; you can have modules which depend on a pre-processed module
305           and full interactive checking will still be available in those
306           modules.</para>
307
308         <para>Because Visual Haskell is using GHC as a backend for its
309           interactive editing features, it supports the full GHC language,
310           including all extensions.</para>
311       </section>
312
313       <section>
314         <title>Using Projects</title>
315         <para>(ToDo: more detail here)</para>
316       </section>
317
318     </section>
319   </article>