Commit fd7692a4 authored by Ian D. Bollinger's avatar Ian D. Bollinger
Browse files

First draft of README alterations

* Rename README files to README.md and link from root.
* Rename HACKING to HACKING.md and link from root.
* Add additional links.
* A fair amount of added punctuation and rewording.
* Replace references to darcs/trac with git/github.
parent f1117f0d
The Cabal library package
=========================
[Cabal home page](http://www.haskell.org/cabal/)
The [Cabal web site].
If you also want the `cabal` command line program then you need
the `cabal-install` package in addition to this library.
If you also want the `cabal` command-line program, you need the
[cabal-install] package in addition to this library.
[cabal-install]: ../cabal-install/README.md
Installation instructions for the Cabal library
===============================================
......@@ -13,13 +14,14 @@ Installation instructions for the Cabal library
If you have the `cabal` program already
---------------------------------------
In this case it's simple, just
In this case it is simple, just run
cabal install
$ cabal install
However, if you do not have an existing version of the `cabal` program,
you first must install the Cabal library. To avoid this bootstrapping
problem, you can install the Cabal library directly as described below.
Of course, if you don't have an existing version of the `cabal` program
then to get one you'd first need to install the Cabal library! To avoid
this bootstrapping problem, you can install the Cabal library directly:
Installing as a user (no root or administrator access)
------------------------------------------------------
......@@ -31,61 +33,64 @@ Installing as a user (no root or administrator access)
Note the use of the `--user` flag at the configure step.
Compiling Setup rather than using `runghc Setup` is much faster and works on
Windows. For all packages other than Cabal itself it is fine to use `runghc`.
Compiling 'Setup' rather than using `runghc Setup` is much faster and
works on Windows. For all packages other than Cabal itself, it is fine
to use `runghc`.
This will install into `$HOME/.cabal/` on unix and into
`$Documents and Settings\$User\Application Data\cabal\` on Windows
If you want to install elsewhere use the `--prefix=` flag at the
This will install into `$HOME/.cabal/` on Unix and into
`Documents and Settings\$User\Application Data\cabal\` on Windows.
If you want to install elsewhere, use the `--prefix=` flag at the
configure step.
Installing as root / Administrator
----------------------------------
Installing as root or Administrator
-----------------------------------
ghc -threaded --make Setup
./Setup configure
./Setup build
sudo ./Setup install
Compiling Setup rather than using `runghc Setup` is much faster and works on
Windows. For all packages other than Cabal itself it is fine to use `runghc`.
Compiling Setup rather than using `runghc Setup` is much faster and
works on Windows. For all packages other than Cabal itself, it is fine
to use `runghc`.
This will install into `/usr/local` on unix and on Windows it will
install into `$ProgramFiles/Haskell`. If you want to install
elsewhere use the `--prefix=` flag at the configure step.
This will install into `/usr/local` on Unix, and on Windows it will
install into `$ProgramFiles/Haskell`. If you want to install elsewhere,
use the `--prefix=` flag at the configure step.
Working with older versions of GHC and Cabal
============================================
It is recommended just to leave any pre-existing version of Cabal
installed. In particular it is *essential* to keep the version that
came with GHC itself since other installed packages need it (eg the
"ghc" api package).
It is recommended that you leave any pre-existing version of Cabal
installed. In particular, it is *essential* you keep the version that
came with GHC itself, since other installed packages require it (for
instance, the "ghc" API package).
Prior to GHC 6.4.2 however, GHC didn't deal particularly well with
having multiple versions of packages installed at once. So if you
are using GHC 6.4.1 or older and you have an older version of Cabal
installed, you probably just want to remove it:
Prior to GHC 6.4.2, however, GHC did not deal particularly well with
having multiple versions of packages installed at once. So if you are
using GHC 6.4.1 or older and you have an older version of Cabal
installed, you should probably remove it by running:
ghc-pkg unregister Cabal
$ ghc-pkg unregister Cabal
or if you had Cabal installed just for your user account then:
or, if you had Cabal installed only for your user account, run:
ghc-pkg unregister Cabal --user
$ ghc-pkg unregister Cabal --user
The `filepath` dependency
=========================
Cabal now uses the `filepath` package so that must be installed first.
GHC-6.6.1 and later come with `filepath` however earlier versions do not by
default. If you do not already have `filepath` then you need to install it. You
can use any existing version of Cabal to do that. If you have neither Cabal or
filepath then it is slightly harder but still possible.
Cabal uses the `filepath` package, so it must be installed first.
GHC version 6.6.1 and later come with `filepath`, however, earlier
versions do not by default. If you do not already have `filepath`,
you need to install it. You can use any existing version of Cabal to do
that. If you have neither Cabal nor `filepath`, it is slightly
harder but still possible.
Unpack Cabal and filepath into separate directories. For example:
Unpack Cabal and `filepath` into separate directories. For example:
tar -xzf filepath-1.1.0.0.tar.gz
tar -xzf Cabal-1.6.0.0.tar.gz
......@@ -101,68 +106,62 @@ Unpack Cabal and filepath into separate directories. For example:
./setup build
./setup install
This installs filepath so you are then in a position to install Cabal by the
normal method.
This installs `filepath` so you are then in a position to install Cabal
by the normal method.
More Information
More information
================
Please see the web site for the [user guide] and API documentation.
There is some more information available on the [development wiki].
Please see the [Cabal web site] for the [user guide] and [API
documentation]. There is additional information available on the
[development wiki].
[user guide]: http://www.haskell.org/cabal/
[development wiki]: http://hackage.haskell.org/trac/hackage/
[user guide]: http://www.haskell.org/cabal/users-guide
[API documentation]: http://www.haskell.org/cabal/release/cabal-latest/doc/API/Cabal/Distribution-Simple.html
[development wiki]: https://github.com/haskell/cabal/wiki
Bugs
=======
====
Please report bugs and wish-list items in our [bug tracker].
Please report bugs and feature requests to Cabal's [bug tracker].
[bug tracker]: https://github.com/haskell/cabal/issues
Your Help
Your help
---------
To help us in the next round of development work it would be
enormously helpful to know from our users what their most pressing
problems are with Cabal and Hackage. You probably have a favourite
Cabal bug or limitation. Take a look at our [bug tracker]. Make sure
the problem is reported there and properly described. Comment on the
ticket to tell us how much of a problem the bug is for you. Add
yourself to the ticket's cc list so we can discuss requirements and
keep you informed on progress. For feature requests it is very
helpful if there is a description of how you would expect to
interact with the new feature.
To help Cabal's development, it is enormously helpful to know from
Cabal's users what their most pressing problems are with Cabal and
[Hackage]. You may have a favourite Cabal bug or limitation. Look at
Cabal's [bug tracker]. Ensure that the problem is reported there and
adequately described. Comment on the issue to report how much of a
problem the bug is for you. Subscribe to the issues's notifications to
discussed requirements and keep informed on progress. For feature
requests, it is helpful if there is a description of how you would
expect to interact with the new feature.
Code
=======
You can get the code from the web page; the version control system we
use is very open and welcoming to new developers.
[Hackage]: http://hackage.haskell.org
You can get the main development branch:
> darcs get --partial http://darcs.haskell.org/cabal
Source code
===========
and you can get the stable 1.6 branch:
You can get the master development branch using:
> darcs get --partial http://darcs.haskell.org/cabal-branches/cabal-1.6
$ git clone https://github.com/haskell/cabal.git
Credits
=======
Cabal Coders (in alphabetical order):
Cabal developers (in alphabetical order):
- Krasimir Angelov
- Bjorn Bringert
- Duncan Coutts
- Isaac Jones
- David Himmelstrup (Lemmih)
- David Himmelstrup ("Lemmih")
- Simon Marlow
- Ross Patterson
- Thomas Schilling
......@@ -170,10 +169,14 @@ Cabal Coders (in alphabetical order):
- Malcolm Wallace
- and nearly 30 other people have contributed occasional patches
Cabal spec:
Cabal specification authors:
- Isaac Jones
- Simon Marlow
- Ross Patterson
- Simon Peyton Jones
- Malcolm Wallace
[bug tracker]: https://github.com/haskell/cabal/issues
[Cabal web site]: http://www.haskell.org/cabal/
If you want to hack on Cabal, don't be intimidated!
Read the guide to the source code:
Read the guide to the source code at:
https://github.com/haskell/cabal/wiki/Source-Guide
Subscribe to the mailing list:
Subscribe to the mailing list at:
http://www.haskell.org/mailman/listinfo/cabal-devel
Browse the list of open issues:
Browse the list of open issues at:
https://github.com/haskell/cabal/issues
There are other resources listed on the dev wiki:
There are other resources listed on the development wiki at:
https://github.com/haskell/cabal/wiki
and
http://hackage.haskell.org/trac/hackage/ (old wiki)
In particular, the open tickets and the cabal-devel mailing list
which is a good place to ask questions.
Of particular value are the open issues list and the cabal-devel mailing
list, which is a good place to ask questions.
Dependencies policy
......@@ -22,4 +23,3 @@ Dependencies policy
Cabal's policy is to support being built by versions of GHC that are up
to 3 years old.
......@@ -2,11 +2,11 @@
[![Build Status](https://secure.travis-ci.org/haskell/cabal.png?branch=master)](http://travis-ci.org/haskell/cabal)
This Cabal git repository contains multiple packages:
This Cabal Git repository contains the following packages:
* `Cabal` -- the Cabal library package
* `cabal-install` -- the cabal-install package containing the `cabal` tool.
* (Cabal)[Cabal/README.md]: the Cabal library package
* (cabal-install)[cabal-install/README.md]: the package containing the `cabal` tool
See the README in each subdir for more details.
See [HACKING.md] for information about contributing.
The canonical upstream repo lives at https://github.com/haskell/cabal
The canonical upstream repository is located at https://github.com/haskell/cabal
The cabal-install package
=========================
[Cabal home page](http://www.haskell.org/cabal/)
The `cabal-install` package provides a command line tool called `cabal`. The
tool uses the `Cabal` library and provides a convenient user interface to the
Cabal/Hackage package build and distribution system. It can build and install
both local and remote packages, including dependencies.
Installation instructions for the cabal-install command line tool
=================================================================
The `cabal-install` package requires a number of other packages, most of which
come with a standard ghc installation. It requires the `network` package, which
is sometimes packaged separately by Linux distributions, for example on
debian or ubuntu it is in "libghc6-network-dev".
It requires a few other Haskell packages that are not always installed.
The exact list is specified in the `.cabal` file or in the `bootstrap.sh`
file. All these packages are available from
[Hackage](http://hackage.haskell.org).
Note that on some Unix systems you may need to install an additional zlib
development package using your system package manager, for example on
debian or ubuntu it is in "zlib1g-dev". It is needed is because the
Haskell zlib package uses the system zlib C library and header files.
The `cabal-install` package is now part of the Haskell Platform so you do not
usually need to install it separately. However if you are starting from a
minimal ghc installation then you need to install `cabal-install` manually.
Since it is just an ordinary Cabal package it can be built in the standard
way, but to make it a bit easier we have partly automated the process:
Quickstart on Unix systems
--------------------------
As a convenience for users on Unix systems there is a `bootstrap.sh` script
which will download and install each of the dependencies in turn.
$ ./bootstrap.sh
It will download and install the dependencies. The script will
install the library packages into `$HOME/.cabal/` and the `cabal` program will
be installed into `$HOME/.cabal/bin/`.
You then have two choices:
* put `$HOME/.cabal/bin` on your `$PATH`
* move the `cabal` program somewhere that is on your `$PATH`
The next thing to do is to get the latest list of packages with:
$ cabal update
This will also create a default config file (if it does not already echo exist)
at `$HOME/.cabal/config`
By default cabal will install programs to `$HOME/.cabal/bin`. If you do not
want to add this directory to your `$PATH` then you can change the setting in
the config file, for example you could use:
symlink-bindir: $HOME/bin
Quickstart on Windows systems
-----------------------------
For Windows users we provide a pre-compiled [cabal.exe] program. Just download
it and put it somewhere on your `%PATH%`, for example
`C:\Program Files\Haskell\bin`.
[cabal.exe]: http://haskell.org/cabal/release/cabal-install-latest/cabal.exe
The next thing to do is to get the latest list of packages with
cabal update
This will also create a default config file (if it does not already echo exist)
at `C:\Documents and Settings\username\Application Data\cabal\config`
Using cabal-install
===================
There are two sets of commands: commands for working with a local project build
tree and ones for working with distributed released packages from hackage.
For a list of the full set of commands and the flags for each command see
$ cabal --help
Commands for developers for local build trees
---------------------------------------------
The commands for local project build trees are almost exactly the same as the
`runghc Setup` command line interface that many people are already familiar
with. In particular there are the commands
cabal configure
cabal build
cabal haddock
cabal clean
cabal sdist
The `install` command is somewhat different. It is an all-in-one operation. If
you run
$ cabal install
in your build tree it will configure, build and install. It takes all the flags
that `configure` takes such as `--global` and `--prefix`.
In addition, if any dependencies are not installed it will download and install
them. If can also rebuild packages to ensure a consistent set of dependencies.
Commands for released hackage packages
--------------------------------------
$ cabal update
This command gets the latest list of packages from the hackage server.
Currently this command has to be run manually occasionally, in particular if
you want to install a newly released package.
$ cabal install xmonad
This is the eponymous command. It installs one or more named packages (and all
their dependencies) from hackage.
By default it installs the latest available version however you can optionally
specify exact versions or version ranges. For example `cabal install alex-2.2`
or `cabal install parsec < 3`.
$ cabal list xml
This does a search of the installed and available packages. It does a
case-insensitive substring match on the package name.
The cabal-install package
=========================
[Cabal home page](http://www.haskell.org/cabal/)
The `cabal-install` package provides a command line tool named `cabal`.
It uses the `Cabal` library and provides a convenient user interface to
the Cabal/[Hackage] build automation and package management system. It
can build and install both local and remote packages, including
dependencies.
Installation instructions for the `cabal` command line tool
===========================================================
The `cabal-install` package requires a number of other packages, most of
which come with a standard GHC installation. It requires the [network]
package, which is sometimes packaged separately by Linux distributions;
for example, on Debian or Ubuntu, it is located in the
"libghc6-network-dev" package.
`cabal` requires a few other Haskell packages that are not always
installed. The exact list is specified in the [.cabal] file or in the
[boostrap.sh] file. All these packages are available from [Hackage].
Note that on some Unix systems you may need to install an additional
zlib development package using your system package manager; for example,
on Debian or Ubuntu, it is located in the "zlib1g-dev" package; on
Fedora, it is located in the "zlib-devel" package. It is required
because the Haskell zlib package uses the system zlib C library and
header files.
The `cabal-install` package is now part of the Haskell Platform, so you
do not usually need to install it separately. However, if you are
starting from a minimal GHC installation then you need to install
`cabal-install` manually. Since it is an ordinary Cabal package, it can
be built in the standard way; to facilitate this, the process is
partially automated. It is described below.
[.cabal]: cabal-install.cabal
[network]: http://hackage.haskell.org/package/network
Quick start on Unix systems
---------------------------
As a convenience for users on Unix systems, there is a [bootstrap.sh]
script that will download and install each of the dependencies in turn.
$ ./bootstrap.sh
It will download and install the dependencies. The script will install
the library packages into `$HOME/.cabal/` and the `cabal` program into
`$HOME/.cabal/bin/`.
You then have the choice either to
* place `$HOME/.cabal/bin` on your `$PATH` or
* move the `cabal` program somewhere that is on your `$PATH`.
Next, you can get the latest list of packages by running:
$ cabal update
This will also create a default configuration file (if it does not
already exist) at `$HOME/.cabal/config`
By default, `cabal` will install programs to `$HOME/.cabal/bin`. If you
do not want to add this directory to your `$PATH`, you can change
the setting in the config file; for example, you could use the
following:
symlink-bindir: $HOME/bin
Quick start on Windows systems
------------------------------
For Windows users, a precompiled program, [cabal.exe], is provided.
Download and put it somewhere on your `%PATH%`, for example:
C:\Program Files\Haskell\bin
Next, you can get the latest list of packages by running:
$ cabal update
This will also create a default configuration file (if it does not
already exist) at
`C:\Documents and Settings\username\Application Data\cabal\config`
[cabal.exe]: http://haskell.org/cabal/release/cabal-install-latest/cabal.exe
Using cabal-install
===================
There are two sets of commands: commands for working with a local
project build tree and ones for working with packages distributed
from [Hackage].
For a list of the full set of commands and the flags for each command,
run:
$ cabal help
Commands for developers for local build trees
---------------------------------------------
The commands for local project build trees are almost exactly the same
as the `runghc Setup` command-line interface that you may already be
familiar with. In particular, there are the following commands:
* `cabal configure`
* `cabal build`
* `cabal haddock`
* `cabal clean`
* `cabal sdist`
The `install` command is somewhat different; it is an all-in-one
operation. If you run
$ cabal install
in your build tree, it will configure, build, and install. It takes all
the flags that `configure` takes such as `--global` and `--prefix`.
In addition, `cabal` will download and install any dependencies that are
not already installed. It can also rebuild packages to ensure a
consistent set of dependencies.
Commands for released Hackage packages
--------------------------------------
$ cabal update
This command gets the latest list of packages from the [Hackage] server.
On occasion, this command must be run manually, for instance, if you
want to install a newly released package.
$ cabal install xmonad
This is the eponymous command. It installs one or more named packages,
and all their dependencies, from Hackage.
By default, it installs the latest available version; however, you may
specify exact versions or version ranges. For example,
`cabal install alex-2.2` or `cabal install parsec < 3`.
$ cabal list xml
This does a search of the installed and available packages. It does a
case-insensitive substring match on the package name.
[Hackage]: http://hackage.haskell.org
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