Skip to content

Commit

Permalink
cvs pull
Browse files Browse the repository at this point in the history 
some haddock fixes
updates to the manual (from ross):
  make copyright, maintainer and synopsis optional again.
  document required fields, plus a few assorted tweaks.
  • Loading branch information
@SyntaxPolice
SyntaxPolice committed Feb 26, 2005
1 parent 6544e5e commit 09acfdc
Show file tree
Hide file tree
Showing 3 changed files with 63 additions and 52 deletions.
5 changes: 2 additions & 3 deletions Distribution/PackageDescription.hs
View file
Expand Up @@ -45,6 +45,8 @@ module Distribution.PackageDescription (
emptyPackageDescription,
readPackageDescription,
parseDescription,
StanzaField(..),
LineNo,
basicStanzaFields,
writePackageDescription,
showPackageDescription,
Expand Down Expand Up @@ -605,9 +607,6 @@ errorOut warnings errors = do
checkMissingFields :: PackageDescription -> [Maybe String]
checkMissingFields pkg_descr =
[missingField (pkgName . package) reqNameName
,missingField copyright reqNameCopyright
,missingField maintainer reqNameMaintainer
,missingField synopsis reqNameSynopsis
,missingField (versionBranch .pkgVersion .package) reqNameVersion
]
where missingField :: (PackageDescription -> [a]) -- Field accessor
Expand Down
7 changes: 2 additions & 5 deletions TODO
View file
Expand Up @@ -3,10 +3,7 @@

* Install libraries in $libdir/ghc-$ghc_version/ rather than $libdir.

* Write semantic checker for package description file. start w/
sanity checker. give error if buildInfo field given when no
exposed or hidden modules for a library. Check for required
fields.
* do something with stub files generated by ghc?

* Decide on interface
** Which fields are required, which targets required.
Expand Down Expand Up @@ -54,7 +51,7 @@

* Doc
** do comments have to start in the first column?
** clarify relationship between exposed-modules and modules, etc.
** clarify relationship between other-modules and modules, etc.
** add preprocessor explanation (see bottom of this TODO).
** Fix example for angela, expose Data.Set, etc, not A, B, etc.b
** add information about executable stanzas
Expand Down
103 changes: 59 additions & 44 deletions doc/Cabal.xml
View file
Expand Up @@ -143,6 +143,7 @@ Name: TestPackage
Version: 0.0
License: BSD3
Author: Angela Author
Synopsis: Small package with two programs
Build-Depends: HUnit

Executable: program1
Expand All @@ -163,18 +164,19 @@ Name: TestPackage
Version: 0.0
License: BSD3
Author: Angela Author
Synopsis: Package with library and two programs
Build-Depends: HUnit
Exposed-Modules: A, B, C

Executable: program1
Main-Is: Main.hs
Hs-Source-Dir: prog1
Other-Modules: A, B
Executable: program1
Main-Is: Main.hs
Hs-Source-Dir: prog1
Other-Modules: A, B

Executable: program2
Main-Is: Main.hs
Hs-Source-Dir: prog2
Other-Modules: A, C, Utils</programlisting>
Executable: program2
Main-Is: Main.hs
Hs-Source-Dir: prog2
Other-Modules: A, C, Utils</programlisting>
<para>with <filename>Setup.hs</filename> the same as above.</para>
</example>

Expand Down Expand Up @@ -272,38 +274,43 @@ Other-Modules: A, C, Utils</programlisting>
<literal>build-depends</literal> field, where the commas are
mandatory.</para>

<para>Some fields are marked as required. All others are optional,
and unless otherwise specified have empty default values.</para>

<para>The first stanza describes the package
as a whole, as well as the library it contains (if any), using
the following fields:</para>
<variablelist>
<varlistentry>
<term>
<literal>name:</literal> <replaceable>identifier</replaceable>
(required)
</term>
<listitem>
<para>The unique name of the package, without the version number
(required).</para>
<para>The unique name of the package, without the version
number.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<literal>version:</literal> <replaceable>numbers</replaceable>
(required)
</term>
<listitem>
<para>The package version number, usually consisting of
a sequence of natural numbers separated by dots
(required).</para>
<para>The package version number, usually consisting of a
sequence of natural numbers separated by dots.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<literal>license:</literal> <replaceable>identifier</replaceable>
(default: <literal>AllRightsReserved</literal>)
</term>
<listitem>
<para>The type of license under which this package is distributed.
License names are the constants of the &License; type.</para>
License names are the constants of the &License; type.</para>
</listitem>
</varlistentry>

Expand All @@ -324,7 +331,9 @@ Other-Modules: A, C, Utils</programlisting>
<replaceable>freeform</replaceable>
</term>
<listitem>
<para>The name of the holder of the copyright on the package.</para>
<para>The content of a copyright notice, typically the name of
the holder of the copyright on the package and the year(s)
from which copyright is claimed.</para>
</listitem>
</varlistentry>

Expand All @@ -344,8 +353,9 @@ Other-Modules: A, C, Utils</programlisting>
<replaceable>address</replaceable>
</term>
<listitem>
<para>The current maintainer of the package, if different
from the author.</para>
<para>The current maintainer or maintainers of the package.
This is an e-mail address to which users should send bug
reports, feature requests and patches.</para>
</listitem>
</varlistentry>

Expand Down Expand Up @@ -386,11 +396,11 @@ Other-Modules: A, C, Utils</programlisting>
<replaceable>freeform</replaceable>
</term>
<listitem>
<para>A very short description of the package,
for use in a table of packages. This is your headline,
so keep it short (one line) but as informative as possible.
Save space by not including the package name or saying
it's written in Haskell.</para>
<para>A very short description of the package, for use in a
table of packages. This is your headline, so keep it short
(one line) but as informative as possible. Save space
by not including the package name or saying it's written
in Haskell.</para>
</listitem>
</varlistentry>

Expand Down Expand Up @@ -447,10 +457,10 @@ Other-Modules: A, C, Utils</programlisting>
<term>
<literal>exposed-modules:</literal>
<replaceable>identifier list</replaceable>
(required if this package contains a library)
</term>
<listitem>
<para>A list of modules added by this package (required if
this package contains a library).</para>
<para>A list of modules added by this package.</para>
</listitem>
</varlistentry>
</variablelist>
Expand Down Expand Up @@ -488,20 +498,22 @@ Other-Modules: A, C, Utils</programlisting>
<term>
<literal>executable:</literal>
<replaceable>freeform</replaceable>
(required)
</term>
<listitem>
<para>The name of the executable program (required).</para>
<para>The name of the executable program.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<literal>main-is:</literal> <replaceable>filename</replaceable>
(required)
</term>
<listitem>
<para>The name of the source file containing the
<literal>Main</literal> module, relative to the
<literal>hs-source-dir</literal> directory (required).</para>
<literal>hs-source-dir</literal> directory.</para>
</listitem>
</varlistentry>
</variablelist>
Expand All @@ -520,10 +532,10 @@ Other-Modules: A, C, Utils</programlisting>
<varlistentry>
<term>
<literal>buildable:</literal> <replaceable>Boolean</replaceable>
(default: <literal>True</literal>)
</term>
<listitem>
<para>Is the component buildable?
(default: <literal>True</literal>.)
Like some of the other fields below, this field is
more useful with the slightly more elaborate form of
the simple build infrastructure described in
Expand All @@ -549,10 +561,11 @@ Other-Modules: A, C, Utils</programlisting>
<term>
<literal>hs-source-dir:</literal>
<replaceable>directory</replaceable>
(default: <quote><literal>.</literal></quote>)
</term>
<listitem>
<para>The name of root directory of the module hierarchy
(default: <quote><literal>.</literal></quote>).</para>
<para>The name of root directory of the module
hierarchy.</para>
</listitem>
</varlistentry>
<varlistentry>
Expand Down Expand Up @@ -629,11 +642,12 @@ Other-Modules: A, C, Utils</programlisting>
<replaceable>filename list</replaceable>
</term>
<listitem>
<para>A list of header files from standard include directories
or those listed in <literal>include-dirs</literal>, typically
containing function prototypes for any foreign imports
used by the package. These will be included in any
compilations via C.</para>
<para>A list of header files from standard
include directories or those listed in
<literal>include-dirs</literal>, to be included in any
compilations via C. These files typically contain
function prototypes for foreign imports used by the
package.</para>
</listitem>
</varlistentry>

Expand All @@ -643,8 +657,9 @@ Other-Modules: A, C, Utils</programlisting>
<replaceable>directory list</replaceable>
</term>
<listitem>
<para>A list of directories to search for
header files.</para>
<para>A list of directories to search for header files,
both when using a C preprocessor and when compiling
via C.</para>
</listitem>
</varlistentry>

Expand Down Expand Up @@ -717,10 +732,10 @@ Other-Modules: A, C, Utils</programlisting>
<replaceable>token list</replaceable>
</term>
<listitem>
<para>On Darwin/MacOS X, a list of
frameworks to link to. Take a look at Apple's developer
documentation to find out what frameworks actually are.
This entry is ignored on all other platforms.</para>
<para>On Darwin/MacOS X, a list of frameworks to link to.
See Apple's developer documentation for more details
on frameworks. This entry is ignored on all other
platforms.</para>
</listitem>
</varlistentry>
</variablelist>
Expand All @@ -733,13 +748,13 @@ Other-Modules: A, C, Utils</programlisting>
<para>For some packages, implementation details and the build
procedure depend on the build environment. The simple build
infrastructure can handle many such situations using a slightly
extended <filename>Setup.hs</filename>:</para>
longer <filename>Setup.hs</filename>:</para>
<programlisting>
import Distribution.Simple
main = defaultMainWithHooks defaultUserHooks</programlisting>

<para>This differs from <literal>defaultMain</literal> in two
ways:</para>
<para>This program differs from <literal>defaultMain</literal>
in two ways:</para>
<orderedlist>
<listitem>
<para>If the package root directory contains a file called
Expand Down Expand Up @@ -977,7 +992,7 @@ runhaskell Setup.hs unregister --gen-script</screen>
registered by running the <filename>register.sh</filename> script.
The <filename>unregister.sh</filename> script would be used
in the uninstall procedure of the package. Similar steps may
be used for creating binary backages for Windows.</para>
be used for creating binary packages for Windows.</para>
</example>

<para>The following options are understood by all commands:</para>
Expand Down

0 comments on commit 09acfdc

Please sign in to comment.