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" [
6 <article id="visual-haskell">
10 <title>Visual Haskell User's Guide</title>
12 <author><othername></othername></author>
13 <address><email>glasgow-haskell-{users,bugs}@haskell.org</email></address>
24 <section id="sec-introduction">
25 <title>Introduction</title>
27 <para>Visual Haskell is a plugin for Microsoft's Visual Studio
28 development environment to support development of Haskell software.
29 Like the other Visual languages, Visual Haskell integrates with the
30 Visual Studio editor to provide interactive features to aid Haskell
31 development, and it enables the construction of projects consisting of
32 multiple Haskell modules.</para>
34 <section id="sec-obtaining">
35 <title>Installing Visual Haskell</title>
37 <para>In order to use Visual Haskell, you need <ulink url="http://msdn.microsoft.com/vstudio/productinfo/">Visual Studio .NET
38 2003</ulink>. Right now, this is the only supported version of Visual
39 Studio - unfortunately we haven't yet added support for the 2005
40 Beta. The Express languages (Visual C++ Express etc.) also will not
41 work, because they don't have support for plugins.</para>
43 <para>You don't need to install GHC separately: Visual Haskell
44 is bundled with a complete GHC distribution, and various other tools
45 (Happy, Alex, Haddock).</para>
47 <para>The latest Visual Haskell installer can be obtained from
51 url="http://research.microsoft.com/downloads/"><literal>http://research.microsoft.com/downloads/</literal></ulink></para>
54 <section id="release-notes">
55 <title>Release Notes</title>
58 <title>Version 0.0, first release</title>
60 <para>This release is a technology preview, and should be considered
61 alpha quality. It works for us, but you are fairly likely to
62 encounter problems. If you're willing to try it out and report
63 bugs, we'd be grateful for the feedback.</para>
67 <para>This release of Visual Haskell is bundled with a
68 development snapshot of GHC, version 6.5 from around 14
69 September 2005. This version of GHC is used to provide the
70 interactive editing features, and will be used to compile all
71 code inside Visual Haskell. It is possible that in future
72 releases we may be able to relax this tight coupling between
73 Visual Haskell and the bundled GHC.</para>
75 <para>Please note that future releases of Visual
76 Haskell will update the compiler, and hence the
77 packages, and so may break your code. Also note that because
78 the bundled GHC is not a released version, it may have bugs and
79 quirks itself: please report them as usual to
80 <email>glasgow-haskell-bugs@haskell.org</email>.</para>
86 <section id="sec-bugs">
87 <title>Getting support, reporting bugs</title>
88 <para>Please report bugs to
89 <email>glasgow-haskell-bugs@haskell.org</email> (subscribe <ulink url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs">here</ulink>), clearly indicating
90 that your bug report relates to Visual Haskell, and giving as much
91 information as possible so that we can reproduce the bug. Even if
92 you can't reproduce the bug reliably, it is still useful to report
93 what you've seen.</para>
95 <para>For help and support, use the
96 <email>glasgow-haskell-users@haskell.org</email> (subscribe <ulink
97 url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-users">here</ulink>) mailing list.</para>
100 <section id="sec-license">
101 <title>License</title>
103 <para>The license is the standard Microsoft Shared Source license. We may be
104 able to relax certain aspects of this license in future releases
105 (please contact us if this license is unsuitable for you). The
106 license is as follows:</para>
109 <para>This Microsoft Research Shared Source license agreement ("MSR-SSLA")
110 is a legal agreement between you and Microsoft Corporation
111 ("Microsoft" or "we") for the software or data identified above, which
112 may include source code, and any associated materials, text or speech
113 files, associated media and "online" or electronic documentation and
114 any updates we provide in our discretion (together, the "Software").</para>
116 <para>By installing, copying, or otherwise using this Software, found at
117 http://research.microsoft.com/downloads, you agree to be bound by the
118 terms of this MSR-SSLA. If you do not agree, do not install copy or
119 use the Software. The Software is protected by copyright and other
120 intellectual property laws and is licensed, not sold.
123 <para>SCOPE OF RIGHTS:
126 <para>You may use, copy, reproduce, and distribute this Software for any
127 non-commercial purpose, subject to the restrictions in this
128 MSR-SSLA. Some purposes which can be non-commercial are teaching,
129 academic research, public demonstrations and personal
130 experimentation. You may also distribute this Software with books or
131 other teaching materials, or publish the Software on websites, that
132 are intended to teach the use of the Software for academic or other
133 non-commercial purposes.
136 <para>You may not use or distribute this Software or any derivative works in
137 any form for commercial purposes. Examples of commercial purposes
138 would be running business operations, licensing, leasing, or selling
139 the Software, distributing the Software for use with commercial
140 products, using the Software in the creation or use of commercial
141 products or any other activity which purpose is to procure a
142 commercial gain to you or others.
145 <para>If the Software includes source code or data, you may create
146 derivative works of such portions of the Software and distribute the
147 modified Software for non-commercial purposes, as provided herein.
150 <para>In return, we simply require that you agree:
153 <para>1. That you will not remove any copyright or other notices from the Software.
156 <para>2. That if any of the Software is in binary format, you will not
157 attempt to modify such portions of the Software, or to reverse
158 engineer or decompile them, except and only to the extent authorized
162 <para>3. That if you distribute the Software or any derivative works of the
163 Software, you will distribute them under the same terms and conditions
164 as in this license, and you will not grant other rights to the
165 Software or derivative works that are different from those provided by
169 <para>4. That if you have created derivative works of the Software, and
170 distribute such derivative works, you will cause the modified files to
171 carry prominent notices so that recipients know that they are not
172 receiving the original Software. Such notices must state: (i) that you
173 have changed the Software; and (ii) the date of any changes.
176 <para>5. That Microsoft is granted back, without any restrictions or
177 limitations, a non-exclusive, perpetual, irrevocable, royalty-free,
178 assignable and sub-licensable license, to reproduce, publicly perform
179 or display, install, use, modify, distribute, make and have made, sell
180 and transfer your modifications to and/or derivative works of the
181 Software source code or data, for any purpose.
184 <para>6. That any feedback about the Software provided by you to us is
185 voluntarily given, and Microsoft shall be free to use the feedback as
186 it sees fit without obligation or restriction of any kind, even if the
187 feedback is designated by you as confidential.
190 <para>7. THAT THE SOFTWARE COMES "AS IS", WITH NO WARRANTIES. THIS MEANS NO
191 EXPRESS, IMPLIED OR STATUTORY WARRANTY, INCLUDING WITHOUT LIMITATION,
192 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, ANY
193 WARRANTY AGAINST INTERFERENCE WITH YOUR ENJOYMENT OF THE SOFTWARE OR
194 ANY WARRANTY OF TITLE OR NON-INFRINGEMENT. THERE IS NO WARRANTY THAT
195 THIS SOFTWARE WILL FULFILL ANY OF YOUR PARTICULAR PURPOSES OR
196 NEEDS. ALSO, YOU MUST PASS THIS DISCLAIMER ON WHENEVER YOU DISTRIBUTE
197 THE SOFTWARE OR DERIVATIVE WORKS.
200 <para>8. THAT NEITHER MICROSOFT NOR ANY CONTRIBUTOR TO THE SOFTWARE WILL BE
201 LIABLE FOR ANY DAMAGES RELATED TO THE SOFTWARE OR THIS MSR-SSLA,
202 INCLUDING DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL OR INCIDENTAL
203 DAMAGES, TO THE MAXIMUM EXTENT THE LAW PERMITS, NO MATTER WHAT LEGAL
204 THEORY IT IS BASED ON. ALSO, YOU MUST PASS THIS LIMITATION OF
205 LIABILITY ON WHENEVER YOU DISTRIBUTE THE SOFTWARE OR DERIVATIVE WORKS.
208 <para>9. That we have no duty of reasonable care or lack of negligence, and
209 we are not obligated to (and will not) provide technical support for
213 <para>10. That if you breach this MSR-SSLA or if you sue anyone over patents
214 that you think may apply to or read on the Software or anyone's use of
215 the Software, this MSR-SSLA (and your license and rights obtained
216 herein) terminate automatically. Upon any such termination, you shall
217 destroy all of your copies of the Software immediately. Sections 5,
218 6, 7, 8, 9, 10, 13 and 14 of this MSR-SSLA shall survive any
219 termination of this MSR-SSLA.
222 <para>11. That the patent rights, if any, granted to you in this MSR-SSLA
223 only apply to the Software, not to any derivative works you make.
226 <para>12. That the Software may be subject to U.S. export jurisdiction at
227 the time it is licensed to you, and it may be subject to additional
228 export or import laws in other places. You agree to comply with all
229 such laws and regulations that may apply to the Software after
230 delivery of the software to you.
233 <para>13. That all rights not expressly granted to you in this MSR-SSLA are
237 <para>14. That this MSR-SSLA shall be construed and controlled by the laws
238 of the State of Washington, USA, without regard to conflicts of law.
239 If any provision of this MSR-SSLA shall be deemed unenforceable or
240 contrary to law, the rest of this MSR-SSLA shall remain in full effect
241 and interpreted in an enforceable manner that most nearly captures the
242 intent of the original language.
245 <para>Copyright © Microsoft Corporation. All rights reserved.
252 <section id="sec-using">
253 <title>Using Visual Haskell</title>
256 <title>Overview of features</title>
258 <para>The following features are provided in the Visual Studio editor
259 when editing Haskell code:</para>
263 <para>Automatic checking of code as you type, and visual indication
264 of parse errors, scoping errors and type errors.</para>
268 <para>Quick info: hovering the mouse over an identifier pops up
269 an information box, including the type of the identifier.</para>
273 <para>A drop-down bar at the top of the editing window lists the
274 top-level declarations in the module, and allows quick navigation
275 to a declaration.</para>
279 <para>Name completion for identifiers in scope: press Ctrl+Space
280 after a partial identifier to see the completions.</para>
284 <para>Go to declaration: right clicking on an identifier and
285 selecting "Go to declaration" will jump the cursor to the
286 declaration of the identifier. This works for locally-defined
287 identifiers and those defined in another module of the project; it
288 does not work for library functions currently.</para>
293 <para>The following features are provided by the project system for
294 constructing Haskell projects:</para>
298 <para>Multi-module Haskell projects are fully supported, based on the
299 <ulink url="http://www.haskell.org/cabal">Cabal</ulink>
300 infrastructure. A project in Visual Haskell <emphasis>is</emphasis>
301 a Cabal package, and vice-versa. A Visual Studio project can be
302 taken to a machine without Visual Haskell and built/installed as a
303 normal Cabal package, and an existing Cabal package can be edited
304 directly in Visual Haskell<footnote><para>This works as long as the
305 Cabal package is using Cabal's simple build system; Cabal
306 packages using their own build systems cannot be edited in Visual
312 <para>Editing of most of the package meta-data is supported through
313 the project property pages.</para>
317 <para>The interactive editing features work across multiple modules in
318 a project. When one module is edited, changes are automatically
319 propagated to dependent modules, even if the edited module has not yet
324 <para>Building is supported through the Cabal build system, and build
325 errors are communicated back to the editor and placed in the task
326 list. Use any of the Visual Studio build commands (e.g. Build
327 Project from the context menu on the project, or Ctrl-Shift-B to
328 build the whole solution).</para>
334 <title>Getting Started</title>
336 <para>To start using Visual Haskell right away, first create a new
337 project (File->New->Project...). Select one of the Haskell
338 project types (Console Application or Library Package), and hit Ok.
339 The project will be created for you, and an example module
340 added: <literal>Main.hs</literal> for an application, or
341 <literal>Module1.hs</literal> for a library.</para>
343 <para>You can now start adding code to
344 <literal>Main.hs</literal>, or adding new modules. To add a new
345 module, right-click on the <literal>src</literal> directory, and
346 select Add->New Item. Visual Haskell supports hierarchical
347 modules too: you can add new folders using the same Add menu to
348 create new nodes in the hierarchy.</para>
350 <para>If you have any errors in your code, they will be underlined with
351 a red squiggly line. Select the Tasks window (usually a tab near the
352 bottom of the Visual Studio window) to see the error messages, and
353 click on an error message to jump to it in the editor.</para>
355 <para>To build the program, hit Ctrl-Shift-B, or select one of the
356 options from the Build menu.</para>
360 <title>Editing Haskell code</title>
362 <para>(ToDo: more detail here)</para>
364 <para>Your module must be plain Haskell (<literal>.hs</literal>) for the interactive features to
365 fully work. If your module is pre-processed with CPP or Literate
366 Haskell, then Visual Haskell will only check the module when it is
367 saved; between saves the source will not be checked for errors and
368 the type information will not be updated. If the source file is
369 pre-processed with Happy or another pre-processor, then you may have
370 to build the project before the type information will be updated
371 (because the pre-processor is only run as part of the build
372 process). Pre-processed source files work fine in a multi-module
373 setting; you can have modules which depend on a pre-processed module
374 and full interactive checking will still be available in those
377 <para>Because Visual Haskell is using GHC as a backend for its
378 interactive editing features, it supports the full GHC language,
379 including all extensions.</para>
383 <title>Using Projects</title>
384 <para>(ToDo: more detail here)</para>