[cvs pull from ross
ijones@syntaxpolice.org**20051016030450] {
hunk ./doc/Cabal.xml 8
- Haddock'>
+ alex'>
+ autoconf'>
+ c2hs'>
+ cpphs'>
+ haddock'>
+ haddock'>
+ happy'>
hunk ./doc/Cabal.xml 23
- distribution of Haskell software. It does this by specifying a
- number of interfaces between package authors, builders and users,
- as well as providing a library implementing these interfaces.
+ distribution of Haskell
+ software. It does this by specifying a number of interfaces between
+ package authors, builders and users, as well as providing a library
+ implementing these interfaces.
hunk ./doc/Cabal.xml 307
- .gc (GreenCard),
- .chs (c2hs),
+ .gc (&Greencard;),
+ .chs (&C2hs;),
hunk ./doc/Cabal.xml 311
- .ly (happy),
- .x (alex)
+ .ly (&Happy;),
+ .x (&Alex;)
hunk ./doc/Cabal.xml 314
- .cpphs (cpphs).
+ .cpphs (&Cpphs;).
hunk ./doc/Cabal.xml 507
+
+
+
+
+
+ data-files:
+ filename list
+
+
+ A list of files to be installed for run-time use by
+ the package. This is useful for packages that use a
+ large amount of static data, such as tables of values
+ or code templates. For details on how to find these
+ files at run-time, see
+ .
hunk ./doc/Cabal.xml 680
- {-# LANGUAGE CPP, MultiParamTypeClasses #-}
+ {-# LANGUAGE CPP, MultiParamTypeClasses #-}
+
+ GHC doesn't support the LANGUAGE
+ pragma yet.
+
hunk ./doc/Cabal.xml 851
+
+
+
+ Accessing data files from package code
+ The placement on the target system of files listed in the
+ data-files field varies between systems, and in
+ some cases one can even move packages around after installation
+ (see ). To enable packages
+ to find these files in a portable way, Cabal generates a module
+ called Paths_pkgname
+ (with any hyphens in pkgname replaced
+ by underscores) during building, so that it may be imported by
+ modules of the package. This module defines a function
+ getDataFileName :: FilePath -> IO FilePath
+ If the argument is a filename listed in the
+ data-files field, the result is the name
+ of the corresponding file on the system on which the program
+ is running.
hunk ./doc/Cabal.xml 890
- be a script produced by the autoconf
+ be a script produced by the &Autoconf;
hunk ./doc/Cabal.xml 939
- (This example is for people familiar with the autoconf
+ (This example is for people familiar with the &Autoconf;
hunk ./doc/Cabal.xml 1043
- The --with-hc,
- --with-hc-pkg and
- --prefix options to the
+ The ,
+ ,
+ , ,
+ ,
+ and options to the
hunk ./doc/Cabal.xml 1053
- the --copy-prefix option to the
+ the --destdir option to the
hunk ./doc/Cabal.xml 1055
- prefix variable on the invocation of
- make install.
+ destdir variable on the invocation of
+ make copy. The supplied
+ Makefile should provide a
+ copy target, which will probably
+ look like this:
+
+copy :
+ $(MAKE) install prefix=$(destdir)/$(prefix) \
+ bindir=$(destdir)/$(bindir) \
+ libdir=$(destdir)/$(libdir) \
+ datadir=$(destdir)/$(datadir) \
+ libexecdir=$(destdir)/$(libexecdir)
+
+
hunk ./doc/Cabal.xml 1075
- interface of , possibly using the
- Cabal library for part of the work. One option is to copy the
- source of Distribution.Simple, and alter it for your needs.
- Good luck.
+ interface of , possibly using
+ the Cabal library for part of the work. One option is to
+ copy the source of Distribution.Simple,
+ and alter it for your needs. Good luck.
hunk ./doc/Cabal.xml 1096
- runhugs, runghc or
- runnhc. The command
+ runhugs, runghc or
+ runnhc. The command
hunk ./doc/Cabal.xml 1136
-runhaskell Setup.hs copy --copy-prefix=/tmp/mypkg/usr
+runhaskell Setup.hs copy --destdir=/tmp/mypkg
hunk ./doc/Cabal.xml 1184
- Prepare to build the package.
- Typically, this step checks that the target platform is capable
- of building the package, and discovers platform-specific features
- that are needed during the build. In addition to the general
- options, this command recognizes the following
+ Prepare to build the package. Typically, this step checks
+ that the target platform is capable of building the package,
+ and discovers platform-specific features that are needed during
+ the build.
+
+ The user may also adjust the behaviour of later stages using
+ the options listed in the following subsections. In the simple
+ build infrastructure, the values supplied via these options are
+ recorded in a private file read by later stages.
+
+ If a user-supplied configure
+ script is run (see
+ or ), it is passed the
+ , ,
+ , ,
+ , and
+ options, plus any unrecognized
+ options.
+
+
+ Programs used for building
+
+ The following options govern the programs used to process
+ the source files of a package:
+
+
+
+ or
+ or
+
+
+ Specify which Haskell implementation to use to build
+ the package. At most one of these flags may be given.
+ If none is given, the implementation under which the setup
+ script was compiled or interpreted is used.
+
+
+
+
+ =path
+ or path
+
+ Specify the path to a particular compiler. If given,
+ this must match the implementation selected above.
+ The default is to search for the usual name of the
+ selected implementation.
+
+
+
+
+ =path
+
+ Specify the path to the package tool, e.g.
+ ghc-pkg.
+
+
+
+
+ =path
+
+ Specify the path to &Haddock;.
+
+
+
+
+ =path
+
+ Specify the path to &Happy;.
+
+
+
+
+ =path
+
+ Specify the path to &Alex;.
+
+
+
+
+ =path
+
+ Specify the path to hsc2hs.
+
+
+
+
+ =path
+
+ Specify the path to &C2hs;.
+
+
+
+
+ =path
+
+ Specify the path to &Greencard;.
+
+
+
+
+ =path
+
+ Specify the path to &Cpphs;.
+
+
+
+
+
+
+
+ Installation paths
+
+ The following options govern the location of installed files
+ from a package:
+
+
+
+ =dir
+
+ The root of the installation, for example
+ /usr/local on a Unix system, or
+ C:\Program Files on a Windows system.
+ The other installation paths are usually subdirectories of
+ prefix, but they don't have
+ to be.
+
+
+
+
+ =dir
+
+ Executables that the user might invoke are installed here.
+
+
+
+
+ =dir
+
+ Object-code libraries are installed here.
+
+
+
+
+ =dir
+
+ A subdirectory of libdir
+ in which libraries are actually installed. For example,
+ in the simple build system on Unix, the default
+ libdir is
+ /usr/local/lib, and
+ libsubdir contains the package
+ identifier and compiler,
+ e.g. mypkg-0.2/ghc-6.4, so libraries
+ would be installed in
+ /usr/local/lib/mypkg-0.2/ghc-6.4.
+
+ Not all build systems make use of
+ libsubdir, in particular the
+ &Make; system does not.
+
+
+
+
+ =dir
+
+ Architecture-independent data files are installed
+ here.
+
+
+
+
+ =dir
+
+ A subdirectory of datadir
+ in which data files are actually installed. This option
+ is similar to --libsubdir in that
+ not all build systems make use of it.
+
+
+
+
+ =dir
+
+ Executables that are not expected to be invoked
+ directly by the user are installed here.
+
+
+
+
+
+ Paths in the simple build system
+
+ For the simple build system, the following defaults
+ apply:
+
+
+
+
+
+
+
+
+
+ Option
+ Windows Default
+ Unix Default
+
+
+
+
+ --prefix
+ C:\Program Files
+ /usr/local
+
+
+
+ --bindir
+ $prefix\$pkgid
+ $prefix/bin
+
+
+
+ --libdir
+ $prefix\Haskell
+ $prefix/lib
+
+
+
+ --libsubdir (Hugs)
+ hugs\packages\$pkg
+ hugs/packages/$pkg
+
+
+
+ --libsubdir (others)
+ $pkgid\$compiler
+ $pkgid/$compiler
+
hunk ./doc/Cabal.xml 1423
-
-
- =dir
-
- Specify the installation prefix
- (default: /usr/local on Unix systems,
- the Program Files folder on Windows, e.g.
- C:\Program Files in an English
- locale).
-
-
+
+ --datadir (executable)
+ $prefix
+ $prefix/share
+
hunk ./doc/Cabal.xml 1429
-
- or
- or
-
-
- Specify which Haskell implementation to use to build
- the package. At most one of these flags may be given.
- If none is given, the implementation under which the setup
- script was compiled or interpreted is used.
-
-
+
+ --datadir (library)
+ C:\Program Files\Common Files
+ $prefix/share
+
hunk ./doc/Cabal.xml 1435
-
- =path
- or path
-
- Specify the path to a particular compiler. If given,
- this must match the implementation selected above.
- The default is to search for the usual name of the
- selected implementation.
-
-
+
+ --datasubdir
+ $pkgid
+ $pkgid
+
hunk ./doc/Cabal.xml 1441
-
- =path
-
- Specify the path to the package tool, e.g.
- ghc-pkg.
-
-
+
+ --libexecdir
+ $prefix\$pkgid
+ $prefix/libexec
+
+
+
+
hunk ./doc/Cabal.xml 1450
-
- =path
-
- Specify the path to &Haddock;.
-
-
+ The following strings are substituted into directory
+ names:
hunk ./doc/Cabal.xml 1453
-
- =path
-
- Specify the path to happy.
-
-
+
+
+ $prefix
+
+ The value of prefix
+
+
+
+ $pkgid
+
+ The full package identifier, e.g. pkg-0.1
+
+
+
+ $compiler
+
+ The compiler and version, e.g. ghc-6.4.1
+
+
+
+ $pkg
+
+ The name of the package only
+
+
+
+ $version
+
+ The version of the package
+
+
+
+
hunk ./doc/Cabal.xml 1487
-
- =path
-
- Specify the path to alex.
-
-
+
+ Prefix-independence
hunk ./doc/Cabal.xml 1490
-
- =path
-
- Specify the path to hsc2hs.
-
-
+ On Windows (and perhaps other OSs), it is possible
+ to query the pathname of the running binary. This means
+ that we can construct an installable executable package
+ that is independent of its absolute install location.
+ The executable can find its auxiliary files by finding its
+ own path and knowing the location of the other files relative
+ to bindir. Prefix-independence is
+ particularly useful: it means the user can choose the install
+ location (i.e. the value of prefix)
+ at install-time, rather than having to bake the path into
+ the binary when it is built.
hunk ./doc/Cabal.xml 1502
-
- =path
-
- Specify the path to c2hs.
-
-
+ In order to achieve this, we require
+ that for an executable on Windows, all
+ of bindir,
+ libdir,
+ datadir and
+ libexecdir begin with
+ $prefix. An error will be returned
+ from setup configure if this is not
+ the case.
hunk ./doc/Cabal.xml 1512
-
- =path
-
- Specify the path to greencard.
-
-
+ The application need do nothing special to achieve
+ prefix-independence. If it finds any files using
+ getDataFileName and the other functions
+ provided for the purpose (see ),
+ the files will be accessed relative to the location of the
+ current executable.
hunk ./doc/Cabal.xml 1519
-
- =path
-
- Specify the path to cpphs.
-
-
+ A library cannot (currently) be prefix-independent,
+ because it will be linked into an executable whose
+ filesystem location bears no relation to the library
+ package.
+
+
hunk ./doc/Cabal.xml 1526
-
-
-
- Allow dependencies to be satisfied by the user package
- database, in addition to the global database.
-
-
+
+ Miscellaneous options
hunk ./doc/Cabal.xml 1529
-
-
-
- (default) Dependencies must be satisfied by the global
- package database.
-
-
+
+
+
+
+ Allow dependencies to be satisfied by the user package
+ database, in addition to the global database.
+
+
hunk ./doc/Cabal.xml 1538
-
- or
-
-
- Request that an additional version of the library
- with profiling features enabled be built and installed
- (only for implementations that support profiling).
-
-
+
+
+
+ (default) Dependencies must be satisfied by the global
+ package database.
+
+
hunk ./doc/Cabal.xml 1546
-
-
-
- (default) Do not generate an additional profiling
- version of the library.
-
-
+
+ or
+
+
+ Request that an additional version of the library
+ with profiling features enabled be built and installed
+ (only for implementations that support profiling).
+
+
hunk ./doc/Cabal.xml 1556
-
-
-
- Any executables generated should have profiling enabled
- (only for implementations that support profiling). For this
- to work, all libraries used by these executables must also
- have been built with profiling support.
-
-
+
+
+
+ (default) Do not generate an additional profiling
+ version of the library.
+
+
hunk ./doc/Cabal.xml 1564
-
-
-
- (default) Do not enable profiling in generated
- executables.
-
-
-
+
+
+
+ Any executables generated should have profiling enabled
+ (only for implementations that support profiling). For this
+ to work, all libraries used by these executables must also
+ have been built with profiling support.
+
+
hunk ./doc/Cabal.xml 1574
- In the simple build infrastructure, an additional option
- is recognized:
-
-
- =dir or
- dir
-
- Specify the directory into which the package will be
- built (default: dist/build).
-
-
-
+
+
+
+ (default) Do not enable profiling in generated
+ executables.
+
+
+
hunk ./doc/Cabal.xml 1583
- In the simple build infrastructure, the values supplied via
- these options are recorded in a private file for use by later
- stages.
+ In the simple build infrastructure, an additional option
+ is recognized:
+
+
+ =dir or
+ dir
+
+ Specify the directory into which the package will be
+ built (default: dist/build).
+
+
+
hunk ./doc/Cabal.xml 1596
- If a user-supplied configure script is
- run (see ), it is passed the
- option and any unrecognized options.
+
hunk ./doc/Cabal.xml 1617
+
+ The install locations are determined by options to
+ setup configure
+ (see ).
hunk ./doc/Cabal.xml 1652
- =path
+ =path
hunk ./doc/Cabal.xml 1655
- installed files. If this is not given, the
- argument of the option to
- configure is used.
+ installed files. If this is not given, then the root
+ directory is assumed.
hunk ./doc/Cabal.xml 1775
- c-sources and extra-source-files
- fields.
+ c-sources, data-files and
+ extra-source-files fields.
}