Skip to content

GitLab

Commit 0a53171b authored by Leonid Onokhov's avatar Leonid Onokhov
Browse files

Fix code highlighting issues in docs

parent a863575a
Hide whitespace changes
Inline Side-by-side
Cabal/doc/developing-packages.rst
View file @ 0a53171b
......@@ -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,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
......@@ -1325,9 +1326,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 +1455,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 +2110,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 +2132,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 +2167,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 +2220,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 +2309,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 +2355,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 +2379,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 +2402,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) \
......
Cabal/doc/installing-packages.rst
View file @ 0a53171b
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
......
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