[Pkg-haskell-commits] darcs: policy: Rewrite policy, describe binary dependencies and installation directories.
Joachim Breitner
mail at joachim-breitner.de
Fri Nov 5 15:02:56 UTC 2010
Fri Nov 5 14:41:29 UTC 2010 Joachim Breitner <mail at joachim-breitner.de>
* Rewrite policy, describe binary dependencies and installation directories.
Ignore-this: e67a66216b2d25a98fbe8b06ff04c908
M ./haskell-policy.sgml -324 +115
Fri Nov 5 14:41:29 UTC 2010 Joachim Breitner <mail at joachim-breitner.de>
* Rewrite policy, describe binary dependencies and installation directories.
Ignore-this: e67a66216b2d25a98fbe8b06ff04c908
diff -rN -u old-policy/haskell-policy.sgml new-policy/haskell-policy.sgml
--- old-policy/haskell-policy.sgml 2010-11-05 15:02:56.366328468 +0000
+++ new-policy/haskell-policy.sgml 2010-11-05 15:02:56.366328468 +0000
@@ -1,18 +1,16 @@
<!doctype debiandoc public "-//DebianDoc//DTD DebianDoc//EN"
[
-<!entity version "0.1.6">
+<!entity version "0.2.0">
<!entity must "<em>must</em>">
<!entity mustnot "<em>must not</em>">
<!entity should "<em>should</em>">
<!entity shouldnot "<em>should not</em>">
-<!entity haskellunsafe
- "<qref id="haskellunsafe">Haskell Unsafe</qref>">
<!entity mailinglist
- "<qref id="mailinglist">Haskell mailing list</qref>">
+ "<qref id="mailinglist">Debian Haskell Group mailing list</qref>">
<!entity mailinglistemail
- "<email>debian-haskell at lists.urchin.earth.li</email>">
+ "<email>debian-haskell at lists.debian.org</email>">
<!entity mailinglisthttpaddress
- "http://urchin.earth.li/mailman/listinfo/debian-haskell">
+ "http://lists.debian.org/debian-haskell/">
]
>
@@ -22,18 +20,21 @@
<book id="haskell-policy">
<titlepag>
<title>Haskell Policy</title>
- <author><name>Ian Lynagh</name><email>igloo at earth.li</email></author>
+ <author><name>Joachim Breitner</name><email>nomeata at debian.org</email></author>
<version>&version;</version>
<abstract>
- This document describes the packaging of Haskell within the
- Debian Operating System and the policy requirements for
- packaged Haskell programs and modules.
+ This document describes the packaging of Haskell libraries for the
+ Debian Operating System. Just as the Debian policy, its aim is to
+ document best practice.
</abstract>
<copyright>
<copyrightsummary>
- Copyright © 2004 Ian Lynagh
+ Copyright © 2004 Ian Lynagh (pre-0.2-versions of this document)
+ </copyrightsummary>
+ <copyrightsummary>
+ Copyright © 2010 Joachim Breitner (0.2 rewrite)
</copyrightsummary>
<p>
This program is free software; you can redistribute it
@@ -68,24 +69,15 @@
<chapt id="introduction">
<heading>Introduction</heading>
+
+<!--
<sect id="definitions">
<heading>Definitions</heading>
<p>
- In this manual we refer to a <em>Haskell compiler</em> when
- we mean a program that translates Haskell code to an
- executable program, such as <prgn>ghc</prgn> or
- <prgn>nhc98</prgn>, and <em>Haskell interpreter</em> when we
- mean a program that executes Haskell code itself, such as
- <prgn>ghci</prgn> or <prgn>hugs</prgn>. To refer
- to something that may be either a Haskell compiler or a
- Haskell interpreter we use the phrase <em>Haskell
- implementation</em>.
- </p>
-
- <p>
We use &should;, &shouldnot;, &must; and &mustnot; as
defined in <prgn>RFC 2119</prgn>.
</p>
+-->
<sect id="mailinglist">
<heading>Mailing List</heading>
@@ -96,315 +88,114 @@
<url id="&mailinglisthttpaddress;" name="the list homepage">.
</p>
- <sect id="haskellunsafe">
- <heading>Haskell Unsafe apt repository</heading>
- <p>
- <url
- id="http://haskell-unsafe.alioth.debian.org/haskell-unsafe.html"
- name="Haskell Unsafe"> is an apt repository for Debian
- packages that are not suitable for uploading to Debian. For
- example, they may be software in the early phases of
- development or backports of software to stable. See the
- above page for details of how to get upload access to it.
- </p>
- </chapt>
-
- <chapt id="implementations">
- <heading>Haskell Implementations</heading>
-
- <sect id="usr-bin-haskell-compiler">
- <heading><file>/usr/bin/haskell-compiler</file></heading>
- <p>
- All Haskell compilers &should; provide the
- <prgn>haskell-compiler</prgn> virtual package and a
- <file>/usr/bin/haskell-compiler</file>.
- {XXX The virtual package doesn't currently exist}
- Packages &mustnot;
- provide one of these but not the other.
- The <file>/usr/bin/haskell-compiler</file> must handle
- argument as follows:
- <enumlist>
- <item>
- If given an argument <tt><var>x</var>.hs</tt> or
- <tt><var>x</var>.lhs</tt> is given then that argument is
- treated as a Haskell input file to be compiled.
- </item>
- <item>
- If given an argument <tt><var>x</var>.o</tt> then that
- argument is treated as an object file and linked
- into the executable.
- </item>
- <item>
- If given an argument <tt>-c</tt> than the Haskell
- input file will be compiled to an object file for
- use in a larger program or library. Behaviour is
- undefined if fewer or more than one Haskell input
- file, or any object files, are given as arguments.
- </item>
- <item>
- If given an argument <tt>-o</tt> followed by another
- argument <tt><var>x</var></tt> will create the output
- program, or object file if <tt>-c</tt> has also been
- given, to the filename <tt><var>x</var></tt>.
- </item>
- <item>
- The arguments <tt>-O0</tt>, <tt>-O1</tt>,
- <tt>-O2</tt>, <tt>-O3</tt>, <tt>-O4</tt>,
- <tt>-O</tt> and <tt>-Os</tt> will not change the
- behaviour other than to potentially affect the
- performance of the resulting code.
- </item>
- <item>
- The argument <tt>-Wall</tt> will not change the
- behaviour other than to potentially alter what
- warnings are given by the compiler during
- compilation.
- </item>
- </enumlist>
- Behaviour is additionally undefined if:
- <enumlist>
- <item>
- Any other arguments are given.
- </item>
- <item>
- No Haskell source files or object files are given as
- arguments.
- </item>
- </enumlist>
- </p>
-
- <p>
- If a package provides <file>/usr/bin/haskell-compiler</file>
- then this &must; compile programs according to the
- <url id="http://www.haskell.org/definition/"
- name="Haskell 98 Report (Revised) and Approved Addenda">.
- {XXX This is a moving target. What should we do about it?}
- </p>
-
- <p>
- If a compiler does provide a
- <file>/usr/bin/haskell-compiler</file> then it &must; use
- the alternatives system to do so.
- It &must; also provide a manpage
- <file>/usr/share/man/man1/haskell-compiler.1.gz</file> as a
- slave. {XXX is this right? Should a manpage with the info
- above be provided by haskell-utils or somesuch?}.
- The priority used by packages providing a
- <file>/usr/bin/haskell-compiler</file> should be agreed by
- concensus on the &mailinglist;.
- </p>
- </sect>
-
- <sect id="haskell-utils">
- <heading><prgn>haskell-utils</prgn></heading>
- <p>
- All Haskell implementation &should; register with
- <prgn>haskell-utils</prgn>. See its manpage for details.
- </p>
- </sect>
-
- <sect>
- <heading>Library dependencies</heading>
- <p>
- An additional requirement on implementations is given in
- <qref id="library_impl_deps">Compiler Dependencies</qref>.
- </p>
- </sect>
- </chapt>
-
- <chapt id="libraries">
- <heading>Haskell Libraries</heading>
-
- <sect>
- <heading>Package Names</heading>
- <p>
- It is strongly recommended that only
- <url id="http://www.haskell.org/cabal/" name="cabalised">
- libraries are packaged. If you wish to package a
- non-cabalised library then the recommended approach is to
- first cabalise it, forwarding the patch upstream.
- </p>
-
- <p>
- Cabal package names match the regex
- <tt>[a-zA-Z][-a-zA-Z0-9]*</tt>, and the tools that
- manipulate them are case preserving only.
- For your package, calculate the <tt><var>cname</var></tt> from the
- Cabal package name by converting all uppercase letters to
- lowercase. If it is desirable for multiple versions of the
- same cabal package to be installed at once on a Debian
- system then you may append <tt>-<var>cversion</var></tt>,
- where <tt><var>cversion</var></tt> is the cabal version,
- to <tt><var>cname</var></tt>.
- </p>
-
- <p>
- The Debian source package &should; be called
- <tt>lib<var>cname</var></tt> and, for each implementation
- <tt><var>impl</var></tt> that it is built for, it &should; make a
- <tt>lib<var>impl</var>-<var>cname</var>-dev</tt> binary
- package. XXX this needs more thought.
- </p>
-
- <p>
- If multiple cabal packages are in a single upstream tarball,
- and repacking them separately does not seem sensible then
- a suitable source package name should be chosen instead.
- A separate binary package for each cabal package, following
- the naming scheme above, &should; still be created.
- </p>
- </sect>
-
- <sect id="library_impl_deps">
- <heading>Library dependencies</heading>
- <p>
- Some Haskell compilers, such as GHC, perform cross-module
- optimisations, such as inlining. This means that even small
- internal changes to a library <tt><var>foo</var></tt> can
- cause programs that link with a library
- <tt><var>bar</var></tt> which, in turn, uses
- <tt><var>foo</var></tt> to fail to link, or even to link
- successfully but give incorrect results. Therefore
- libraries &must; depend on the exact version of other
- Haskell libraries that they were compiled against.
- Furthermore, they must build-depend on the exact version of
- the Haskell libraries they use in order to keep the packages
- in sync across all arches.
- </p>
-
- <p>
- An exception is made for the libraries shipped with
- compilers. The reasons for this are:
- <list>
- <item>
- Many of the libraries currently shipped with
- compilers will be used by very few libraries.
- Should a library need to be changed in a Debian
- release the compiler package &must; conflict with
- those packages affected.
- </item>
- <item>
- While an upload of a library to fix other packaging
- issues will result in only a handful, at most, of
- packages needing to be (needlessly) recompiled, such
- an upload of a compiler would require all libraries
- to be (needlessly) recompiled.
- </item>
- </list>
- Thus we believe this policy gives the best tradeoff between
- maintainers having to be careful about conflicts when they
- make changes and not wasting too many CPU cycles on
- unnecessary recompilation.
- </p>
-
- <p>
- For simplicity's sake we will use this dependency scheme for
- all Haskell implementations. As almost all libraries are
- expected to be compiled for GHC this should not affect when
- recompilation is necessary. All Haskell implementations
- &must; provide a file
- <file>/usr/lib/compiler/debian-dependencies</file>
- that contains how the library must depend on the compiler,
- e.g.
- <tt>ghc6 (>= 6.2.1), ghc6 (<< 6.2.1+)</tt>.
- </p>
- </sect>
-
- <sect>
- <heading>Install-time compilation</heading>
- <p>
- The possibility of compiling libraries at install time was
- considered, but was rejected due to its fragility and due to
- it being against the spirit of Debian being a binary
- districution.
- </p>
- </sect>
-
- <sect>
- <heading>Built libraries</heading>
- <p>
- All libraries &should; be built for all released compilers in
- Debian for which they are buildable. Libraries &shouldnot;
- be built for unreleased compilers, such as CVS snapshots,
- without good reason, as uploads of new versions of these
- would require new uploads of all such libraries, and their
- reverse dependencies, too. However, you can upload libraries
- built against unreleased compilers to &haskellunsafe;.
- </p>
-
- <p>
- Although there is no technical reason why all libraries need
- be in the same place, in order to make life easier for users
- all libraries &should; be installed into
- <file>/usr/lib/haskell-libraries/compiler/package/</file>
- where <file>compiler</file> is the source package
- name of the compiler they are to be used with.
- </p>
- </sect>
-
- <sect>
- <heading>Documentation</heading>
- <p>
- For each cabal package <var>cp</var>, a manual
- page <file><var>cp</var>.3haskell</file> describing the purpose
- of the package and the list of modules it includes &should;
- be installed into <file>/usr/share/man/man3</file>.
- Additionally, for each module
- <var>Hierarchial.Module</var>, a manual page
- <file><var>cp</var>.<var>Hierarchial.Module</var>.3haskell</file>
- dsecribing the purpose and interface of the module &should;
- be installed into <file>/usr/share/man/man3</file>.
- XXX We'd like to mention haddock here, but it can't output
- manual pages yet, can it?
- </p>
-
- <p>
- Additionally, you &should; provide documentation in other
- formats such as, but not limited to, plain text and HTML in
- <file>/usr/share/doc/package</file>. It is expected
- that most libraries will provide documentation in the form
- accepted by haddock, making this easy.
- </p>
- </sect>
</chapt>
- <chapt id="programs">
- <heading>Haskell Programs</heading>
- <p>
- As with libraries, the recommended was of packaging Haskell
- programs is to first cabalise them if they are not already
- cabalised. The package name, both binary and source, should
- then be derived from the cabal package name in the same way
- as for libraries. Programs needing Haskell 98 and approved
- addenda only &should; use
- <file>/usr/bin/haskell-compiler</file> to build. Otherwise,
- your package should build-depend on suitable compilers,
- prefering those that produce better code.
- </p>
+ <chapt id="libs-bin">
+ <heading>Haskell Libraries — binary packages</heading>
- <p>
- As normal, each executable should install a Manual page with
- the extension <file>.1</file> into
- <file>/usr/share/man/man1</file>.
- </p>
- </chapt>
-
- <chapt id="testsuites">
- <heading>Testsuites</heading>
- <p>
- For both libraries and programs you &should;, in the source
- package, include a pair of shell scripts
- <file>debian/haskell-testsuite-inplace</file> and
- <file>debian/haskell-testsuite-installed</file>. If these
- exist they &must; run a testsuite, using the library or
- program in the build tree or from the installed package
- respectively. The build dependencies &must; be sufficient to
- run the testsuites. The testsuites &mustnot; be interactive.
- The inplace testsuite &should; be run as part of the package
- build; normally, if the testsuite fails the build should
- also fail.
- </p>
- </chapt>
+ <sect id="libs-bin-types">
+ <heading>Package types</heading>
+ <p>
+ For each packaged Cabal library, up to three binary packages are
+ built:
+ <enumlist>
+ <item>The library itself.
+ <item>The documentation package.
+ <item>The profiling package.
+ </enumlist>
+ The latter two are optional and can be omitted if there are valid
+ reasons to do so.
+
+ <sect id="libs-bin-names">
+ <heading>Package names</heading>
+ <p>
+ The name of the Debian packages for a given haskell library are
+ derived from the Cabal name of the library in question, following
+ these rules:
+ <enumlist>
+ <item>All characters are lower-cased.
+ <item>Underscores are turned into dashes.
+ <item>The name is prepended with <tt>libghc6-</tt>. This name
+ will change if the major version of GHC used in Debian changes.
+ <item>If there is more than one version of this Cabal package to
+ be shipped with Debian, a significant part of the Version number
+ is appended.
+ <item>The name is appended with <tt>-dev</tt>, <tt>-doc</tt> or
+ <tt>-prof</tt>, depending on the type of the package.
+ </enumlist>
+ </p>
+
+ <sect id="libs-bin-abi-names">
+ <heading>Virtual ABI packages</heading>
+ <p>
+ The library and profiling library also have a <em>virtual ABI
+ package name</em>. It is calculated by the same rules, but does not
+ allow for a version number after the Cabal name and appends,
+ separated by dashes, the cabal version and the first five characters
+ of the ABI hash, lowercased. The ABI hash can be obtained using
+ <tt>ghc-pkg field <var>pkg</var> id | cut -d- -f3</tt>.
+
+ <sect id="libs-bin-relationships">
+ <heading>Package relationships</heading>
+ <p>
+ Between the possibly three packages per Cabal library, the following
+ relations should be in place:
+ <enumlist>
+ <item>The library package suggests the documentation and the
+ profiling packages, if they exist.
+ <item>The documentation package suggests the library
+ package.
+ <item>The profiling package depends on the library package with
+ an exact version constraing on the binary version.
+ </enumlist>
+ <p>
+ The library and profiling package should <tt>Provide</tt> their
+ respective virtual ABI package name.
+
+ <p>
+ The library and profiling package depends, for each Haskell library
+ [...incomplete...]
More information about the Pkg-haskell-commits
mailing list