Commit 1fcc8042 authored by Mikhail Glushenkov's avatar Mikhail Glushenkov Committed by GitHub
Browse files

Merge pull request #3831 from sopvop/master

More docs highlighting changes
parents 17352791 42411899
......@@ -37,7 +37,7 @@ copyright = u'2016, Cabal Team'
release = version # The full version, including alpha/beta/rc tags.
# Syntax highlighting
highlight_language = 'haskell'
highlight_language = 'cabal'
#pygments_style = 'tango'
# List of patterns, relative to source directory, that match files and
......@@ -209,18 +209,20 @@ class CabalLexer(lexer.RegexLexer):
name = 'Cabal'
aliases = ['cabal']
filenames = ['.cabal']
flags = re.MULTILINE# | re.DOTALL
flags = re.MULTILINE
tokens = {
'root' : [
(r'\n', token.Text),
(r'^\s*(--.*)$', token.Comment.Single),
(r'[^\S\n]+', token.Text),
(r'(\n\s*|\t)', token.Whitespace),
(r'&&|\|\||==|<=|>=|<|>|^=', token.Operator),
(r',', token.Punctuation),
(r'^\s*([\w\-_]+:)', token.Keyword),
(r'^\s*([\w\-_]+)(\s+)([\w\-_]+).*$', lexer.bygroups(token.Keyword, token.Whitespace, token.Name)),
(r'.', token.Text)
(r'\n', token.Text),
(r'^\s*(--.*)$', token.Comment.Single),
# key: value
(r'^(\s*)([\w\-_]+)(:)',
lexer.bygroups(token.Whitespace, token.Keyword, token.Punctuation)),
(r'^([\w\-_]+)', token.Keyword), # library, executable, flag etc.
(r'[^\S\n]+', token.Text),
(r'(\n\s*|\t)', token.Whitespace),
(r'&&|\|\||==|<=|>=|<|>|^>=', token.Operator),
(r',|:|{|}', token.Punctuation),
(r'.', token.Text)
],
}
......@@ -6,6 +6,8 @@ Haskell module or two.
Every project needs a name, we'll call this example "proglet".
.. highlight:: console
::
$ cd proglet/
......@@ -80,6 +82,8 @@ some build information about the library or executable.
Editing the .cabal file
-----------------------
.. highlight:: cabal
Load up the ``.cabal`` file in a text editor. The first part of the
``.cabal`` file has the package metadata and towards the end of the file
you will find the ``executable`` or ``library`` section.
......@@ -184,16 +188,16 @@ Building the package
For simple packages that's it! We can now try configuring and building
the package:
::
.. code-block:: console
cabal configure
cabal build
$ cabal configure
$ cabal build
Assuming those two steps worked then you can also install the package:
::
.. code-block:: console
cabal install
$ cabal install
For libraries this makes them available for use in GHCi or to be used by
other packages. For executables it installs the program so that you can
......@@ -564,7 +568,7 @@ The HUnit package contains a file ``HUnit.cabal`` containing:
and the following ``Setup.hs``:
::
.. code-block:: haskell
import Distribution.Simple
main = defaultMain
......@@ -793,7 +797,7 @@ describe the package as a whole:
For build type ``Simple``, the contents of ``Setup.hs`` must be:
::
.. code-block:: haskell
import Distribution.Simple
main = defaultMain
......@@ -802,7 +806,7 @@ describe the package as a whole:
parameters <#system-dependent-parameters>`__ below), the contents of
``Setup.hs`` must be:
::
.. code-block:: haskell
import Distribution.Simple
main = defaultMainWithHooks autoconfUserHooks
......@@ -811,7 +815,7 @@ describe the package as a whole:
packages <installing-packages.html#more-complex-packages>`__ below),
the contents of ``Setup.hs`` must be:
::
.. code-block:: haskell
import Distribution.Make
main = defaultMain
......@@ -1028,9 +1032,9 @@ While developing a package, it is often useful to make its code
available inside an interpreter session. This can be done with the
``repl`` command:
::
.. code-block:: console
cabal repl
$ cabal repl
The name comes from the acronym
`REPL <http://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop>`__,
......@@ -1040,12 +1044,12 @@ components, the name can be given as an argument to ``repl``. The name
can be also optionally prefixed with the component's type for
disambiguation purposes. Example:
::
.. code-block:: console
cabal repl foo
cabal repl exe:foo
cabal repl test:bar
cabal repl bench:baz
$ cabal repl foo
$ cabal repl exe:foo
$ cabal repl test:bar
$ cabal repl bench:baz
Freezing dependency versions
""""""""""""""""""""""""""""
......@@ -1056,9 +1060,9 @@ environment, it may be necessary or desirable to ensure that the same
dependency versions are selected in each environment. This can be done
with the ``freeze`` command:
::
.. code-block:: console
cabal freeze
$ cabal freeze
The command writes the selected version for all dependencies to the
``cabal.config`` file. All environments which share this file will use
......@@ -1072,24 +1076,26 @@ conform to `Package Versioning Policy`_, which is
a recommended versioning system for publicly released Cabal packages.
This is done by running the ``gen-bounds`` command:
::
.. code-block:: console
cabal gen-bounds
$ cabal gen-bounds
For example, given the following dependencies specified in
``build-depends``:
::
foo == 0.5.2
bar == 1.1
build-depends:
foo == 0.5.2
bar == 1.1
``gen-bounds`` will suggest changing them to the following:
::
foo >= 0.5.2 && < 0.6
bar >= 1.1 && < 1.2
build-depends:
foo >= 0.5.2 && < 0.6
bar >= 1.1 && < 1.2
Executables
^^^^^^^^^^^
......@@ -1116,7 +1122,7 @@ Running executables
You can have Cabal build and run your executables by using the ``run``
command:
::
.. code-block:: console
$ cabal run EXECUTABLE [-- EXECUTABLE_FLAGS]
......@@ -1180,9 +1186,8 @@ Example: Package using ``exitcode-stdio-1.0`` interface
The example package description and executable source file below
demonstrate the use of the ``exitcode-stdio-1.0`` interface.
foo.cabal:
::
.. code-block:: cabal
:caption: foo.cabal
Name: foo
Version: 1.0
......@@ -1195,9 +1200,8 @@ foo.cabal:
main-is: test-foo.hs
build-depends: base
test-foo.hs:
::
.. code-block:: haskell
:caption: test-foo.hs
module Main where
......@@ -1216,9 +1220,8 @@ also develops a simple implementation of the interface set by
``Distribution.TestSuite``, but in actual usage the implementation would
be provided by the library that provides the testing facility.
bar.cabal:
.. code-block:: none
.. code-block:: cabal
:caption: bar.cabal
Name: bar
Version: 1.0
......@@ -1232,9 +1235,8 @@ bar.cabal:
build-depends: base, Cabal >= 1.9.2
Bar.hs:
::
.. code-block:: haskell
:caption: Bar.hs
module Bar ( tests ) where
......@@ -1310,9 +1312,9 @@ Example: Package using ``exitcode-stdio-1.0`` interface
The example package description and executable source file below
demonstrate the use of the ``exitcode-stdio-1.0`` interface.
foo.cabal:
::
.. code-block:: cabal
:caption: foo.cabal
:name: foo-bench.cabal
Name: foo
Version: 1.0
......@@ -1325,9 +1327,8 @@ foo.cabal:
main-is: bench-foo.hs
build-depends: base, time
bench-foo.hs:
::
.. code-block:: haskell
:caption: bench-foo.hs
{-# LANGUAGE BangPatterns #-}
module Main where
......@@ -1455,7 +1456,7 @@ system-dependent values for these fields.
modules. From GHC version 6.6 onward, these may be specified by
placing a ``LANGUAGE`` pragma in the source files affected e.g.
::
.. code-block:: haskell
{-# LANGUAGE CPP, MultiParamTypeClasses #-}
......@@ -2110,7 +2111,7 @@ 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
::
.. code-block:: haskell
getDataFileName :: FilePath -> IO FilePath
......@@ -2132,7 +2133,7 @@ functions and values, which record the version of the package and some
other directories which the package has been configured to be installed
into (e.g. data files live in ``getDataDir``):
::
.. code-block:: haskell
version :: Version
......@@ -2167,7 +2168,7 @@ implementation details and the build procedure depend on the build
environment. The ``build-type`` ``Configure`` can be used to handle many
such situations. In this case, ``Setup.hs`` should be:
::
.. code-block:: haskell
import Distribution.Simple
main = defaultMainWithHooks autoconfUserHooks
......@@ -2220,7 +2221,7 @@ This example is for people familiar with the
In the X11 package, the file ``configure.ac`` contains:
::
.. code-block:: shell
AC_INIT([Haskell X11 package], [1.1], [libraries@haskell.org], [X11])
......@@ -2309,7 +2310,7 @@ dependent packages; for example, suppose your package works with either
version 3 or version 4 of the ``base`` package, you could select the
available version in your Haskell modules like this:
::
.. code-block:: cpp
#if MIN_VERSION_base(4,0,0)
... code that works with base-4 ...
......@@ -2355,7 +2356,7 @@ a few options:
and after each command is run, and also to specify additional
preprocessors. A typical ``Setup.hs`` may look like this:
::
.. code-block:: haskell
import Distribution.Simple
main = defaultMainWithHooks simpleUserHooks { postHaddock = posthaddock }
......@@ -2379,7 +2380,7 @@ a few options:
which simply parses the command line arguments and invokes ``make``.
Here ``Setup.hs`` should look like this:
::
.. code-block:: haskell
import Distribution.Make
main = defaultMain
......@@ -2402,7 +2403,7 @@ a few options:
supplied ``Makefile`` should provide a ``copy`` target, which will
probably look like this:
::
.. code-block:: make
copy :
$(MAKE) install prefix=$(destdir)/$(prefix) \
......
Configuration
=============
.. highlight:: cabal
Overview
--------
......@@ -9,7 +11,9 @@ The global configuration file for ``cabal-install`` is
it for you on the first call to ``cabal update``. Alternatively, you can
explicitly ask ``cabal`` to create it for you using
``cabal user-config update``
.. code-block:: console
$ cabal user-config update
Most of the options in this configuration file are also available as
command line arguments, and the corresponding documentation can be used
......@@ -130,7 +134,7 @@ Secure local repositories
If you want to use repositories on your local file system, it is
recommended instead to use a *secure* local repository:
.. code-block:: none
::
repository my-local-repo
url: file:/path/to/local/repo
......@@ -145,39 +149,51 @@ can be used to create and manage such repositories.
Building and installing packages
================================
.. highlight:: console
After you've unpacked a Cabal package, you can build it by moving into
the root directory of the package and running the ``cabal`` tool there:
``cabal [command] [option...]``
::
$ cabal [command] [option...]
The *command* argument selects a particular step in the build/install
process.
You can also get a summary of the command syntax with
``cabal help``
::
$ cabal help
Alternatively, you can also use the ``Setup.hs`` or ``Setup.lhs``
script:
``runhaskell Setup.hs [command] [option...]``
::
$ runhaskell Setup.hs [command] [option...]
For the summary of the command syntax, run:
``cabal help``
::
$ cabal help
or
``runhaskell Setup.hs --help``
::
$ runhaskell Setup.hs --help
Building and installing a system package
----------------------------------------
.. code-block:: bash
::
runhaskell Setup.hs configure --ghc
runhaskell Setup.hs build
runhaskell Setup.hs install
$ runhaskell Setup.hs configure --ghc
$ runhaskell Setup.hs build
$ runhaskell Setup.hs install
The first line readies the system to build the tool using GHC; for
example, it checks that GHC exists on the system. The second line
......@@ -187,11 +203,11 @@ results to some permanent place and registers the package with GHC.
Building and installing a user package
--------------------------------------
.. code-block:: bash
::
runhaskell Setup.hs configure --user
runhaskell Setup.hs build
runhaskell Setup.hs install
$ runhaskell Setup.hs configure --user
$ runhaskell Setup.hs build
$ runhaskell Setup.hs install
The package is installed under the user's home directory and is
registered in the user's package database (``--user``).
......@@ -205,7 +221,7 @@ dependencies in a single step. To do this, run:
::
cabal install [PACKAGE...]
$ cabal install [PACKAGE...]
To browse the list of available packages, visit the
Hackage_ web site.
......@@ -232,7 +248,7 @@ To initialise a fresh sandbox in the current directory, run
``cabal sandbox init``. All subsequent commands (such as ``build`` and
``install``) from this point will use the sandbox.
.. code-block:: bash
::
$ cd /path/to/my/haskell/library
$ cabal sandbox init # Initialise the sandbox
......@@ -245,7 +261,7 @@ unreleased version of a library. This can be done with the
``cabal sandbox add-source`` command - think of it as "local Hackage_".
If an add-source dependency is later modified, it is reinstalled automatically.
.. code-block:: bash
::
$ cabal sandbox add-source /my/patched/library # Add a new add-source dependency
$ cabal install --dependencies-only # Install it into the sandbox
......@@ -261,7 +277,7 @@ the same directory with your ``cabal.sandbox.config`` (which was created
by ``sandbox init``). This file has the same syntax as the main Cabal
config file.
.. code-block:: console
::
$ cat cabal.config
documentation: True
......@@ -271,7 +287,7 @@ config file.
When you have decided that you no longer want to build your package
inside a sandbox, just delete it:
.. code-block:: bash
::
$ cabal sandbox delete # Built-in command
$ rm -rf .cabal-sandbox cabal.sandbox.config # Alternative manual method
......@@ -289,7 +305,7 @@ change tracking. In addition to ``add-source``, there are also
Sometimes one wants to share a single sandbox between multiple packages.
This can be easily done with the ``--sandbox`` option:
.. code-block:: bash
::
$ mkdir -p /path/to/shared-sandbox
$ cd /path/to/shared-sandbox
......@@ -307,7 +323,7 @@ directory (``./.cabal-sandbox``).
Using multiple different compiler versions simultaneously is also
supported, via the ``-w`` option:
.. code-block:: bash
::
$ cabal sandbox init
$ cabal install --only-dependencies -w /path/to/ghc-1 # Install dependencies for both compilers
......@@ -323,7 +339,7 @@ manager tool (e.g. ``ghc-pkg``) tool on the sandbox package DB directly
``cabal sandbox hc-pkg`` command is a convenient wrapper that runs the
compiler-specific package manager tool with the arguments:
.. code-block:: console
::
$ cabal -v sandbox hc-pkg list
Using a sandbox located at /path/to/.cabal-sandbox
......@@ -363,7 +379,7 @@ The sandbox config file can be also specified via the
Finally, the flag ``--ignore-sandbox`` lets you temporarily ignore an
existing sandbox:
.. code-block:: bash
::
$ mkdir my/sandbox
$ cd my/sandbox
......@@ -380,17 +396,17 @@ root directory:
::
runhaskell Setup.hs configure --prefix=/usr
runhaskell Setup.hs build
runhaskell Setup.hs copy --destdir=/tmp/mypkg
tar -czf mypkg.tar.gz /tmp/mypkg/
$ runhaskell Setup.hs configure --prefix=/usr
$ runhaskell Setup.hs build
$ runhaskell Setup.hs copy --destdir=/tmp/mypkg
$ tar -czf mypkg.tar.gz /tmp/mypkg/
If the package contains a library, you need two additional steps:
::
runhaskell Setup.hs register --gen-script
runhaskell Setup.hs unregister --gen-script
$ runhaskell Setup.hs register --gen-script
$ runhaskell Setup.hs unregister --gen-script
This creates shell scripts ``register.sh`` and ``unregister.sh``, which
must also be sent to the target system. After unpacking there, the
......
.. highlight:: console
Cabal is the standard package system for
Haskell_ software. It helps people to
configure, build and install Haskell software and to distribute it
......@@ -60,8 +62,8 @@ Developers can use the tool with packages in local directories, e.g.
::
cd foo/
cabal install
$ 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
......@@ -71,7 +73,7 @@ It is also possible to install several local packages at once, e.g.
::
cabal install foo/ bar/
$ 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
......@@ -81,7 +83,7 @@ with any other suitable archive.
::
cabal install xmonad
$ cabal install xmonad
This will install the ``xmonad`` package plus all of its dependencies.
......@@ -91,8 +93,8 @@ example
::
cabal install foo-1.0.tar.gz
cabal install http://example.com/foo-1.0.tar.gz
$ 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,
......@@ -165,17 +167,17 @@ parameters.
::
./configure --prefix=...
make
make install
$ ./configure --prefix=...
$ make
$ make install
compared to
::
cabal configure --prefix=...
cabal build
cabal install
$ 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
......
.. highlight:: shell
.. highlight:: console
Quickstart
==========
......@@ -9,13 +9,13 @@ local builds with this command (configuring is not necessary):
::
cabal new-build
$ cabal new-build
To open a GHCi shell with this package, use this command:
::
cabal new-repl
$ cabal new-repl
Developing multiple packages
----------------------------
......@@ -44,29 +44,29 @@ this behavior; you will need to upgrade to HEAD.)