Skip to content

GitLab

Commit 02cc8f5c authored by Max Amanshauser's avatar Max Amanshauser
Browse files

docs: move new docs into place [skip ci]

parent b00289b1
Expand all Hide whitespace changes
Inline Side-by-side
Cabal/doc/Cabal.css deleted 100644 → 0
View file @ b00289b1
body {
max-width: 18cm;
}
div {
font-family: sans-serif;
color: black;
background: white
}
h1, h2, h3, h4, h5, h6, p.title { color: #005A9C }
h1 { font: 170% sans-serif }
h2 { font: 140% sans-serif }
h3 { font: 120% sans-serif }
h4 { font: bold 100% sans-serif }
h5 { font: italic 100% sans-serif }
h6 { font: small-caps 100% sans-serif }
pre {
font-family: monospace;
border-width: 1px;
border-style: solid;
padding: 0.3em
}
pre.screen { color: #006400 }
pre.programlisting { color: maroon }
div.example {
margin: 1ex 0em;
border: solid #412e25 1px;
padding: 0ex 0.4em
}
div.example, div.example-contents {
background-color: #fffcf5
}
a:link { color: #0000C8 }
a:hover { background: #FFFFA8 }
a:active { color: #D00000 }
a:visited { color: #680098 }
h1 a:link, h2 a:link, h3 a:link, h4 a:link, h5 a:link, h6 a:link,
h1 a:visited, h2 a:visited, h3 a:visited, h4 a:visited, h5 a:visited, h6 a:visited {
color: #005A9C;
text-decoration: none
}
Cabal/doc/developing-packages.markdown deleted 100644 → 0
View file @ b00289b1
This diff is collapsed.
Cabal/doc/index.markdown deleted 100644 → 0
View file @ b00289b1
% Cabal User Guide
**Version: 1.25.0.0**
Cabal is the standard package system for [Haskell] software. It helps
people to configure, build and install Haskell software and to
distribute it easily to other users and developers.
There is a command line tool called `cabal` for working with Cabal
packages. It helps with installing existing packages and also helps
people developing their own packages. It can be used to work with local
packages or to install packages from online package archives, including
automatically installing dependencies. By default it is configured to
use [Hackage] which is Haskell's central package archive that contains
thousands of libraries and applications in the Cabal package format.
# Contents #
* [Introduction](#introduction)
- [What's in a package](#whats-in-a-package)
- [A tool for working with packages](#a-tool-for-working-with-packages)
* [Building, installing and managing packages](installing-packages.html)
* [Creating packages](developing-packages.html)
* [Reporting bugs and deficiencies](misc.html#reporting-bugs-and-deficiencies)
* [Stability of Cabal interfaces](misc.html#stability-of-cabal-interfaces)
# Introduction #
Cabal is a package system for Haskell software. The point of a package
system is to enable software developers and users to easily distribute,
use and reuse software. A package system makes it easier for developers
to get their software into the hands of users. Equally importantly, it
makes it easier for software developers to be able to reuse software
components written by other developers.
Packaging systems deal with packages and with Cabal we call them _Cabal
packages_. The Cabal package is the unit of distribution. Every Cabal
package has a name and a version number which are used to identify the
package, e.g. `filepath-1.0`.
Cabal packages can depend on other Cabal packages. There are tools
to enable automated package management. This means it is possible for
developers and users to install a package plus all of the other Cabal
packages that it depends on. It also means that it is practical to make
very modular systems using lots of packages that reuse code written by
many developers.
Cabal packages are source based and are typically (but not necessarily)
portable to many platforms and Haskell implementations. The Cabal
package format is designed to make it possible to translate into other
formats, including binary packages for various systems.
When distributed, Cabal packages use the standard compressed tarball
format, with the file extension `.tar.gz`, e.g. `filepath-1.0.tar.gz`.
Note that packages are not part of the Haskell language, rather they
are a feature provided by the combination of Cabal and GHC (and several
other Haskell implementations).
## A tool for working with packages ##
There is a command line tool, called "`cabal`", that users and developers
can use to build and install Cabal packages. It can be used for both
local packages and for packages available remotely over the network. It
can automatically install Cabal packages plus any other Cabal packages
they depend on.
Developers can use the tool with packages in local directories, e.g.
~~~~~~~~~~~~~~~~
cd foo/
cabal install
~~~~~~~~~~~~~~~~
While working on a package in a local directory, developers can run the
individual steps to configure and build, and also generate documentation
and run test suites and benchmarks.
It is also possible to install several local packages at once, e.g.
~~~~~~~~~~~~~~~~
cabal install foo/ bar/
~~~~~~~~~~~~~~~~
Developers and users can use the tool to install packages from remote
Cabal package archives. By default, the `cabal` tool is configured to
use the central Haskell package archive called [Hackage] but it
is possible to use it with any other suitable archive.
~~~~~~~~~~~~~~~~
cabal install xmonad
~~~~~~~~~~~~~~~~
This will install the `xmonad` package plus all of its dependencies.
In addition to packages that have been published in an archive,
developers can install packages from local or remote tarball files,
for example
~~~~~~~~~~~~~~~~
cabal install foo-1.0.tar.gz
cabal install http://example.com/foo-1.0.tar.gz
~~~~~~~~~~~~~~~~
Cabal provides 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. It is not expected that users
will have to modify any of the information in the `.cabal` file.
For full details, see the section on [building and installing
packages](installing-packages.html).
Note that `cabal` is not the only tool for working with Cabal packages.
Due to the standardised format and a library for reading `.cabal` files,
there are several other special-purpose tools.
## What's in a package ##
A Cabal package consists of:
* Haskell software, including libraries, executables and tests
* metadata about the package in a standard human and machine
readable format (the "`.cabal`" file)
* a standard interface to build the package (the "`Setup.hs`" file)
The `.cabal` file contains information about the package, supplied by
the package author. In particular it lists the other Cabal packages
that the package depends on.
For full details on what goes in the `.cabal` and `Setup.hs` files, and
for all the other features provided by the build system, see the section
on [developing packages](developing-packages.html).
## Cabal featureset ##
Cabal and its associated tools and websites covers:
* a software build system
* software configuration
* packaging for distribution
* automated package management
* natively using the `cabal` command line tool; or
* by translation into native package formats such as RPM or deb
* web and local Cabal package archives
* central Hackage website with 1000's of Cabal packages
Some parts of the system can be used without others. In particular the
built-in build system for simple packages is optional: it is possible
to use custom build systems.
## Similar systems ##
The Cabal system is roughly comparable with the system of Python Eggs,
Ruby Gems or Perl distributions. Each system has a notion of
distributable packages, and has tools to manage the process of
distributing and installing packages.
Hackage is an online archive of Cabal packages. It is roughly comparable
to CPAN but with rather fewer packages (around 5,000 vs 28,000).
Cabal is often compared with autoconf and automake and there is some
overlap in functionality. The most obvious similarity is that the
command line interface for actually configuring and building packages
follows the same steps and has many of the same configuration
parameters.
~~~~~~~~~~
./configure --prefix=...
make
make install
~~~~~~~~~~
compared to
~~~~~~~~~~
cabal configure --prefix=...
cabal build
cabal install
~~~~~~~~~~
Cabal's build system for simple packages is considerably less flexible
than make/automake, but has builtin knowledge of how to build Haskell
code and requires very little manual configuration. Cabal's simple build
system is also portable to Windows, without needing a Unix-like
environment such as cygwin/mingwin.
Compared to autoconf, Cabal takes a somewhat different approach to
package configuration. Cabal's approach is designed for automated
package management. Instead of having a configure script that tests for
whether dependencies are available, Cabal packages specify their
dependencies. There is some scope for optional and conditional
dependencies. By having package authors specify dependencies it makes it
possible for tools to install a package and all of its dependencies
automatically. It also makes it possible to translate (in a
mostly-automatically way) into another package format like RPM or deb
which also have automatic dependency resolution.
[Haskell]: http://www.haskell.org/
[Hackage]: http://hackage.haskell.org/
Cabal/doc/installing-packages.markdown deleted 100644 → 0
View file @ b00289b1
This diff is collapsed.
Cabal/doc/misc.markdown deleted 100644 → 0
View file @ b00289b1
% Cabal User Guide
# Reporting bugs and deficiencies #
Please report any flaws or feature requests in the [bug tracker][].
For general discussion or queries email the libraries mailing list
<libraries@haskell.org>. There is also a development mailing list
<cabal-devel@haskell.org>.
[bug tracker]: https://github.com/haskell/cabal/issues
# Stability of Cabal interfaces #
The Cabal library and related infrastructure is still under active
development. New features are being added and limitations and bugs are
being fixed. This requires internal changes and often user visible
changes as well. We therefore cannot promise complete future-proof
stability, at least not without halting all development work.
This section documents the aspects of the Cabal interface that we can
promise to keep stable and which bits are subject to change.
## Cabal file format ##
This is backwards compatible and mostly forwards compatible. New fields
can be added without breaking older versions of Cabal. Fields can be
deprecated without breaking older packages.
## Command-line interface ##
### Very Stable Command-line interfaces ###
* `./setup configure`
* `--prefix`
* `--user`
* `--ghc`, `--uhc`
* `--verbose`
* `--prefix`
* `./setup build`
* `./setup install`
* `./setup register`
* `./setup copy`
### Stable Command-line interfaces ###
### Unstable command-line ###
## Functions and Types ##
The Cabal library follows the [Package Versioning Policy][PVP]. This
means that within a stable major release, for example 1.2.x, there will
be no incompatible API changes. But minor versions increments, for
example 1.2.3, indicate compatible API additions.
The Package Versioning Policy does not require any API guarantees
between major releases, for example between 1.2.x and 1.4.x. In practise
of course not everything changes between major releases. Some parts of
the API are more prone to change than others. The rest of this section
gives some informal advice on what level of API stability you can expect
between major releases.
[PVP]: http://www.haskell.org/haskellwiki/Package_versioning_policy
### Very Stable API ###
* `defaultMain`
* `defaultMainWithHooks defaultUserHooks`
But regular `defaultMainWithHooks` isn't stable since `UserHooks`
changes.
### Semi-stable API ###
* `UserHooks` The hooks API will change in the future
* `Distribution.*` is mostly declarative information about packages and
is somewhat stable.
### Unstable API ###
Everything under `Distribution.Simple.*` has no stability guarantee.
## Hackage ##
The index format is a partly stable interface. It consists of a tar.gz
file that contains directories with `.cabal` files in. In future it may
contain more kinds of files so do not assume every file is a `.cabal`
file. Incompatible revisions to the format would involve bumping the
name of the index file, i.e., `00-index.tar.gz`, `01-index.tar.gz` etc.
[dist-simple]: ../release/cabal-latest/doc/API/Cabal/Distribution-Simple.html
[dist-make]: ../release/cabal-latest/doc/API/Cabal/Distribution-Make.html
[dist-license]: ../release/cabal-latest/doc/API/Cabal/Distribution-License.html#t:License
[extension]: ../release/cabal-latest/doc/API/Cabal/Language-Haskell-Extension.html#t:Extension
[BuildType]: ../release/cabal-latest/doc/API/Cabal/Distribution-PackageDescription.html#t:BuildType
[alex]: http://www.haskell.org/alex/
[autoconf]: http://www.gnu.org/software/autoconf/
[c2hs]: http://www.cse.unsw.edu.au/~chak/haskell/c2hs/
[cpphs]: http://projects.haskell.org/cpphs/
[greencard]: http://hackage.haskell.org/package/greencard
[haddock]: http://www.haskell.org/haddock/
[HsColour]: http://www.cs.york.ac.uk/fp/darcs/hscolour/
[happy]: http://www.haskell.org/happy/
[Hackage]: http://hackage.haskell.org/
[pkg-config]: http://www.freedesktop.org/wiki/Software/pkg-config/
Cabal/doc/nix-local-build.markdown deleted 100644 → 0
View file @ b00289b1
This diff is collapsed.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment