Personal tools

Cabal-make

From HaskellWiki

(Difference between revisions)
Jump to: navigation, search
m (→Get it)
(→Dependencies: simplified)
(15 intermediate revisions not shown.)
Line 7: Line 7:
* Web-based, cross-package links in [[Haddock]] docs (documentation generated by [[Haddock]]).
* Web-based, cross-package links in [[Haddock]] docs (documentation generated by [[Haddock]]).
* Syntax coloring via [[hscolour]], with per-project CSS.
* Syntax coloring via [[hscolour]], with per-project CSS.
-
* Links from the [[Haddock]] docs to [[hscolour]]'d code (per-project, per-module, and per-entity).
+
* Links from the [[Haddock]] docs to [[hscolour]]'d code (per-module, and per-entity).
* Links from [[Haddock]] docs to wiki-based user comment pages (per-project and per-module), with automatic subscription (for email notification).
* Links from [[Haddock]] docs to wiki-based user comment pages (per-project and per-module), with automatic subscription (for email notification).
-
* Set up with [[darcs]] repositories on http://darcs.haskell.org.
+
* Set up with [[darcs]] repositories on http://code.haskell.org or elsewhere.
* Make distribution tarballs and install on server.
* Make distribution tarballs and install on server.
* Automated download and build in a fresh local temp directory for testing.
* Automated download and build in a fresh local temp directory for testing.
-
* Copy [[Haddock]] docs to server
+
* Copy [[Haddock]] docs to server (deprecated now that hackage has caught up with ghc).
* Generate editor tags files (via [[hasktags]]).
* Generate editor tags files (via [[hasktags]]).
* Convert source files between dos-style and unix-style line endings.
* Convert source files between dos-style and unix-style line endings.
* Customizable.
* Customizable.
 +
 +
== Packages using cabal-make ==
 +
 +
To get a concrete sense of the first few of the features listed above, here are some links to docs for packages that use cabal-make. (Please add your own packages to this list when you use cabal-make.)
 +
* [[Phooey]]: a simple, arrow-based functional GUI library
 +
* [[DeepArrow]]: a framework for composable semantic editors
 +
* [[TV]]: combined and separable packaging of functionality and interface
 +
* [[GuiTV]]: GUIs for TV
 +
* [[Checkers]]: Some [[QuickCheck]] helpers
 +
* [[FieldTrip]]: Functional 3D
 +
* [[Reactive]]: Functional reactive programming with a data-driven implementation
== Example use ==
== Example use ==
-
On my Windows system, I've placed cabal-make at <code>c:\Haskell\cabal-make</code>, and I like to install Haskell packages under <code>c:\Haskell\packages</code>. I might write a <code>Makefile</code> for the package [[TV]] as follows:
+
On my Windows system, I've placed cabal-make at <code>c:\Haskell\cabal-make</code>, and I like to install Haskell packages under <code>c:\Haskell\packages</code>. I might write a <code>Makefile</code> for the package [[checkers]] as follows:
{| class="wikitable"
{| class="wikitable"
Line 25: Line 36:
<pre>
<pre>
user = conal
user = conal
-
configure-dirs=--prefix=c:/Haskell/packages --datadir=c:/Haskell/packages
+
cabal-make = c:/conal/Haskell/cabal-make
-
haddock_interfaces=\
+
configure-dirs = --prefix=c:/Haskell/packages --datadir=c:/Haskell/packages --libdir=c:/Haskell/packages --bindir=c:/Haskell/packages/bin
-
http://haskell.org/ghc/docs/latest/html/libraries/base,c:/ghc/ghc-6.6/doc/html/libraries/base/base.haddock \
+
hscolour-css = $(cabal-make)/hscolour.css
-
http://haskell.org/ghc/docs/latest/html/libraries/mtl,c:/ghc/ghc-6.6/doc/html/libraries/mtl/mtl.haddock \
+
-
http://darcs.haskell.org/packages/DeepArrow/doc/html,c:/Haskell/packages/DeepArrow-0.0.1/doc/html/DeepArrow.haddock
+
-
include c:/Haskell/cabal-make/cabal-make.inc
+
server = code.haskell.org
 +
server-dir = /srv/code
 +
server-url-dir =
 +
include ../my-cabal-make.inc
</pre>
</pre>
|}
|}
-
I don't like wiring the interface paths (especially with version numbers) into my makefile, but I don't know how to avoid it. Suggestions, please.
+
To build [[checkers]], I run "<code>make</code>" with targets like "<code>configure</code>", "<code>build</code>", "<code>doc</code>", and "<code>install</code>". Or "<code>all</code>" (default) for all of these targets.
-
 
+
-
To build [[TV]], I run "<code>make</code>" with targets like "<code>configure</code>", "<code>build</code>", "<code>doc</code>", and "<code>install</code>". Or "<code>all</code>" (default) for all of these targets.
+
-
[[Darcs]]-related targets:
+
A few [[darcs]]-related targets:
-
* <code>darcs-repo</code>: makes a repository at http://darcs.haskell.org/packages/TV
+
* <code>pull</code> and <code>push</code>.
-
* <code>darcs-tag</code>: do "<code>darcs tag</code>" using current version (extracted from project [[Cabal]] file)
+
* <code>repo</code>: makes a repository at http://darcs.haskell.org/packages/checkers.
-
* <code>darcs-dist</code>: make a tarball and copy to server
+
* <code>tag</code>: do "<code>darcs tag</code>" using current version (extracted from project [[Cabal]] file)
-
* <code>web-doc</code>: copy docs & colored sources to the server
+
* <code>darcs-dist</code>: make a tarball and copy to server.
-
* <code>test-get-build</code>: Test by doing "<code>darcs get</code>", configure, and build in a fresh temp directory
+
* <code>web-doc</code>: copy docs & colored sources to the server.
 +
* <code>test-get-build</code>: Test by doing "<code>darcs get</code>", configure, and build in a fresh temp directory.
The target "<code>watch-comments</code>" sets up a subscription to the Haskell wiki talk pages that correspond to the package's modules (for the user comment links inserted in the [[Haddock]] docs.)
The target "<code>watch-comments</code>" sets up a subscription to the Haskell wiki talk pages that correspond to the package's modules (for the user comment links inserted in the [[Haddock]] docs.)
Line 67: Line 78:
|}
|}
-
Then I just have to define <code>haddock_interfaces</code> and include <code>my-cabal-make</code>. My [[TV]] <code>Makefile</code> is really
+
Then I just have to define <code>haddock_interfaces</code> and include <code>my-cabal-make</code>. My [[checkers]] <code>Makefile</code> is really
{| class="wikitable"
{| class="wikitable"
| style="padding:0px 20px 0px 20px;" |
| style="padding:0px 20px 0px 20px;" |
<pre>
<pre>
-
haddock_interfaces=\
+
user = conal
-
http://haskell.org/ghc/docs/latest/html/libraries/base,c:/ghc/ghc-6.6/doc/html/libraries/base/base.haddock \
+
cabal-make = c:/Haskell/cabal-make
-
http://haskell.org/ghc/docs/latest/html/libraries/mtl,c:/ghc/ghc-6.6/doc/html/libraries/mtl/mtl.haddock \
+
configure-dirs = --prefix=c:/Haskell/packages --datadir=c:/Haskell/packages
-
http://darcs.haskell.org/packages/DeepArrow/doc/html,c:/Haskell/packages/DeepArrow-0.0.1/doc/html/DeepArrow.haddock
+
hscolour-css = $(cabal-make)/hscolour.css
-
include ../my-cabal-make.inc
+
include $(cabal-make)/cabal-make.inc
</pre>
</pre>
|}
|}
Line 83: Line 94:
== Dependencies ==
== Dependencies ==
-
* Recent [[Cabal]] (1.1.8 or better, or get the latest from [http://darcs.haskell.org/cabal Cabal darcs repo])
+
* [[Cabal]]
-
* Recent [[Haddock]] (0.9 or better, or latest from [http://darcs.haskell.org/haddock Haddock darcs repo])
+
* [[darcs]] for push & pull targets
 +
* [[Haddock]] and [[hscolour]] if you make your own docs
* [http://www.gnu.org/software/make GNU make]
* [http://www.gnu.org/software/make GNU make]
 +
 +
== Use guidelines ==
 +
 +
* In order for cabal-make to work, you have to list each of your source modules on a line by itself, ''including'' the first one in the list (instead of placing it aside the Cabal directive). You can use "<code>make show-modules</code>" to see if your list of source modules is extracted correctly.
 +
* Cabal-make assumes your source code to be under <code>src</code>. Overridable via <code>top-src-dir</code>.
== Get it ==
== Get it ==
Line 99: Line 116:
== To do ==
== To do ==
-
* Eliminate hard-wiring the interface paths into my makefile.
+
* Eliminate the restrictions/assumptions listed in [[#Use guidelines]].
 +
 
 +
[[Category:Tools]]
 +
[[Category:Cabal]]
 +
[[Category:Libraries]]
 +
[[Category:Packages]]

Revision as of 19:50, 11 November 2008

Contents

1 Abstract

Cabal-make is an include file for GNU make files to be used with Cabal in sharing Haskell packages. It is intended mainly for package authors. People who just build & install packages software can do so entirely with Cabal commands. In particular, it's a bit hairy to get the best results from Haddock & hscolour.

2 Features

  • Web-based, cross-package links in Haddock docs (documentation generated by Haddock).
  • Syntax coloring via hscolour, with per-project CSS.
  • Links from the Haddock docs to hscolour'd code (per-module, and per-entity).
  • Links from Haddock docs to wiki-based user comment pages (per-project and per-module), with automatic subscription (for email notification).
  • Set up with darcs repositories on http://code.haskell.org or elsewhere.
  • Make distribution tarballs and install on server.
  • Automated download and build in a fresh local temp directory for testing.
  • Copy Haddock docs to server (deprecated now that hackage has caught up with ghc).
  • Generate editor tags files (via hasktags).
  • Convert source files between dos-style and unix-style line endings.
  • Customizable.

3 Packages using cabal-make

To get a concrete sense of the first few of the features listed above, here are some links to docs for packages that use cabal-make. (Please add your own packages to this list when you use cabal-make.)

  • Phooey: a simple, arrow-based functional GUI library
  • DeepArrow: a framework for composable semantic editors
  • TV: combined and separable packaging of functionality and interface
  • GuiTV: GUIs for TV
  • Checkers: Some QuickCheck helpers
  • FieldTrip: Functional 3D
  • Reactive: Functional reactive programming with a data-driven implementation

4 Example use

On my Windows system, I've placed cabal-make at c:\Haskell\cabal-make, and I like to install Haskell packages under c:\Haskell\packages. I might write a Makefile for the package checkers as follows: 

user = conal
cabal-make = c:/conal/Haskell/cabal-make
configure-dirs = --prefix=c:/Haskell/packages --datadir=c:/Haskell/packages --libdir=c:/Haskell/packages --bindir=c:/Haskell/packages/bin
hscolour-css = $(cabal-make)/hscolour.css

server = code.haskell.org
server-dir = /srv/code
server-url-dir =
include ../my-cabal-make.inc

To build checkers, I run "make" with targets like "configure", "build", "doc", and "install". Or "all" (default) for all of these targets.

A few darcs-related targets:

  • pull and push.
  • repo: makes a repository at http://darcs.haskell.org/packages/checkers.
  • tag: do "darcs tag" using current version (extracted from project Cabal file)
  • darcs-dist: make a tarball and copy to server.
  • web-doc: copy docs & colored sources to the server.
  • test-get-build: Test by doing "darcs get", configure, and build in a fresh temp directory.

The target "watch-comments" sets up a subscription to the Haskell wiki talk pages that correspond to the package's modules (for the user comment links inserted in the Haddock docs.)

There are a few other targets as well. See the source.

5 Specializing

I use a trick for collecting my favorite setting to be saved across my own packages. The file is called "my-cabal-make.inc": 

user = conal
cabal-make = c:/Haskell/cabal-make
configure-dirs = --prefix=c:/Haskell/packages --datadir=c:/Haskell/packages
hscolour-css = $(cabal-make)/hscolour.css

include $(cabal-make)/cabal-make.inc

Then I just have to define haddock_interfaces and include my-cabal-make. My checkers Makefile is really 

user = conal
cabal-make = c:/Haskell/cabal-make
configure-dirs = --prefix=c:/Haskell/packages --datadir=c:/Haskell/packages
hscolour-css = $(cabal-make)/hscolour.css

include $(cabal-make)/cabal-make.inc

6 Dependencies

7 Use guidelines

  • In order for cabal-make to work, you have to list each of your source modules on a line by itself, including the first one in the list (instead of placing it aside the Cabal directive). You can use "make show-modules" to see if your list of source modules is extracted correctly.
  • Cabal-make assumes your source code to be under src. Overridable via top-src-dir.

8 Get it

darcs get --partial http://darcs.haskell.org/cabal-make

9 Customization

There are several customization variables defined in cabal-make that can be overriden. Simply define these variables in your makefile before "cabal-make.inc". See the "Settings" section of the source.

10 To do

Retrieved from "http://www.haskell.org/haskellwiki/Cabal-make"

Categories: Tools | Cabal | Libraries | Packages