-O in 6.8.1-candidate

[Duncan Coutts]

On Fri, 2007-10-19 at 10:42 +0100, Simon Peyton-Jones wrote:
> | In general the users should never have to modify the .cabal file. For
> | the common settings that we expect the user to want to control Cabal
> | provides configure flags.
> |
> 
> ....
> 
> | The idea is that instead of having to find the options for each
> | implementation you might want to use, that Cabal knows the right
> options
> | for each compiler to use a feature like optimisation or profiling or
> | whatever.
> 
> You have a clear mental model of how Cabal is intended to be used --
> although it also provides trapdoors (like ghc-options) for when the
> intended path isn't adequate.  But that mental model is much clearer
> to you and the other Cabal developers than it is to Cabal users like
> Serge and me.
> 
> Would it be worth writing a new section in the Cabal manual that
> describes the "intended use model" for Cabal, for the benefit of Cabal
> users?  That way you'd be able to explain this stuff once and for all.
> 
> Documentation often focuses on the knobs ("turn the steering wheel to
> make the car change direction"), and omit the larger mental model of
> what is going on ("cars should be driven on a road").

Yes. Here's a new introduction for the user's guide. Comments and
improvements welcome.

Duncan


  <sect1 id="intro">
    <title>Introduction</title>
    <para>
      Developers write Cabal packages. These can be for libraries or
      executables. This involves writing the code obviously and also creating a
      <literal>.cabal</literal> file. The .cabal file contains some information
      about the package. Some of this information is needed to actually build
      the package and some is just useful for identifying the package when it
      comes to distribution.
    </para>
    <programlisting>
name:     Foo
version:  1.0

library
  build-depends:   base
  exposed-modules: Foo
    </programlisting>
    <para>
      Users install Cabal packages so they can use them. It is not expected
      that users will have to modify any of the information in the
      <literal>.cabal</literal> file. Cabal does provide a number of ways for
      a user to customise how and where a package is installed. They can decide
      where a package will be installed, which Haskell implementation to use
      and whether to build optimised code or build with the ability to profile
      code.
    </para>
    <programlisting>
tar -xzf Foo-1.0.tar.gz
cd Foo-1.0
cabal-setup configure --with-compiler=ghc-6.4.2 --prefix=$HOME --user
cabal-setup build
cabal-setup install
    </programlisting>
    <para>
      One of the purposes of Cabal is to make it easier to build a package with
      different Haskell implementations. So it provides abstractions of
      features present in different Haskell implementations and wherever
      possible it is best to take advantage of these to increase portability.
      Where necessary however it is possible to use specific features of
      specific implementations. For example one of the pieces of information a
      package author can put in the package's <literal>.cabal</literal> file is
      what language extensions the code uses. This is far preferable to
      specifying flags for a specific compiler as it allows Cabal to pick the
      right flags for the Haskell implementation that the user picks. It also
      allows Cabal to figure out if the language extension is even supported by
      the Haskell implementation that the user picks. Where compiler-specific
      options are needed however, there is an "escape hatch" available. The
      developer can specify implementation-specific options and more generally
      there is a configuration mechanism to customise many aspects of how a
      package is built depending on the Haskell implementation, the Operating
      system, computer architecture and user-specified configuration flags.
    </para>
    <programlisting>
name:     Foo
version:  1.0

library
  build-depends:   base
  exposed-modules: Foo
  extensions:	     ForeignFunctionInterface
  ghc-options:     -Wall
  nhc98-options:   -K4m
  if os(windows)
    build-depends: Win32
    </programlisting>
  </sect1>