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       </section>
 207
 208       <para>The following features are provided by the project system for
 209         constructing Haskell projects:</para>
 210
 211       <itemizedlist>
 212         <listitem>
 213           <para>Multi-module Haskell projects are fully supported, based on the
 214             <ulink url="http://www.haskell.org/cabal">Cabal</ulink>
 215             infrastructure.  A project in Visual Haskell <emphasis>is</emphasis>
 216             a Cabal package, and vice-versa.  A Visual Studio project can be
 217             taken to a machine without Visual Haskell and built/installed as a
 218             normal Cabal package, and an existing Cabal package can be edited
 219             directly in Visual Haskell<footnote><para>This works as long as the
 220                 Cabal package is using Cabal's simple build system; Cabal
 221                 packages using their own build systems cannot be edited in Visual
 222                 Haskell.</para>
 223             </footnote>.</para>
 224         </listitem>
 225
 226         <listitem>
 227           <para>Editing of most of the package meta-data is supported through
 228             the project property pages.</para>
 229         </listitem>
 230
 231         <listitem>
 232           <para>The interactive editing features work across multiple modules in
 233             a project.  When one module is edited, changes are automatically
 234             propagated to dependent modules, even if the edited module has not yet
 235             been saved.</para>
 236         </listitem>
 237
 238         <listitem>
 239           <para>Building is supported through the Cabal build system, and build
 240             errors are communicated back to the editor and placed in the task
 241             list.  Use any of the Visual Studio build commands (e.g. Build
 242             Project from the context menu on the project, or Ctrl-Shift-B to
 243             build the whole solution).</para>
 244         </listitem>
 245
 246       </itemizedlist>
 247
 248     <para>Additionally, Visual Haskell is bundled with a large collection of
 249       documentation: the GHC manual, the hierarchical libraries reference, and
 250       other material all of which can be browsed within Visual Studio
 251       itself.</para>
 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>