Difference between revisions of "Cabal-make"
m (→Get it) |
m |
||
(18 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
+ | <span style="color: red">[WARNING: This page is *extremely* out of date and likely to be obsolete]</span> |
||
+ | |||
== Abstract == |
== Abstract == |
||
Line 7: | Line 9: | ||
* 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 ( |
+ | * 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:// |
+ | * 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 [[ |
+ | 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 38: | ||
<pre> |
<pre> |
||
user = conal |
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 |
||
− | haddock_interfaces=\ |
||
+ | hscolour-css = $(cabal-make)/hscolour.css |
||
− | http://haskell.org/ghc/docs/latest/html/libraries/base,c:/ghc/ghc-6.6/doc/html/libraries/base/base.haddock \ |
||
− | 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 |
||
+ | server = code.haskell.org |
||
⚫ | |||
+ | server-dir = /srv/code |
||
+ | server-url-dir = |
||
⚫ | |||
</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. |
||
⚫ | |||
⚫ | |||
+ | * <code>pull</code> and <code>push</code>. |
||
− | |||
⚫ | |||
⚫ | |||
+ | * <code>tag</code>: do "<code>darcs tag</code>" using current version (extracted from project [[Cabal]] file) |
||
⚫ | |||
− | * <code>darcs- |
+ | * <code>darcs-dist</code>: make a tarball and copy to server. |
− | * <code> |
+ | * <code>web-doc</code>: copy docs & colored sources to the server. |
⚫ | |||
− | * <code>web-doc</code>: copy docs & colored sources to the server |
||
⚫ | |||
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 80: | ||
|} |
|} |
||
− | Then I just have to define <code>haddock_interfaces</code> and include <code>my-cabal-make</code>. My [[ |
+ | 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> |
||
+ | user = conal |
||
− | haddock_interfaces=\ |
||
+ | cabal-make = c:/Haskell/cabal-make |
||
− | http://haskell.org/ghc/docs/latest/html/libraries/base,c:/ghc/ghc-6.6/doc/html/libraries/base/base.haddock \ |
||
⚫ | |||
− | http://haskell.org/ghc/docs/latest/html/libraries/mtl,c:/ghc/ghc-6.6/doc/html/libraries/mtl/mtl.haddock \ |
||
+ | hscolour-css = $(cabal-make)/hscolour.css |
||
− | http://darcs.haskell.org/packages/DeepArrow/doc/html,c:/Haskell/packages/DeepArrow-0.0.1/doc/html/DeepArrow.haddock |
||
− | include |
+ | include $(cabal-make)/cabal-make.inc |
</pre> |
</pre> |
||
|} |
|} |
||
Line 83: | Line 96: | ||
== Dependencies == |
== Dependencies == |
||
+ | * [[Cabal]] |
||
− | * Recent [[Cabal]] (1.1.8 or better, or get the latest from [http://darcs.haskell.org/cabal Cabal darcs repo]) |
||
+ | * [[darcs]] for push & pull targets |
||
− | * Recent [[Haddock]] (0.9 or better, or latest from [http://darcs.haskell.org/haddock Haddock darcs repo]) |
||
+ | * [[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 == |
||
<blockquote> |
<blockquote> |
||
− | <tt>darcs get --partial http:// |
+ | <tt>darcs get --partial http://code.haskell.org/~conal/code/cabal-make</tt> |
</blockquote> |
</blockquote> |
||
Line 99: | Line 118: | ||
== To do == |
== To do == |
||
− | * Eliminate |
+ | * Eliminate the restrictions/assumptions listed in [[#Use guidelines]]. |
+ | |||
+ | [[Category:Tools]] |
||
+ | [[Category:Cabal]] |
||
+ | [[Category:Libraries]] |
||
+ | [[Category:Packages]] |
||
+ | [[Category:Pages to be removed]] |
Latest revision as of 00:56, 12 July 2021
[WARNING: This page is *extremely* out of date and likely to be obsolete]
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.
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.
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
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
andpush
.repo
: makes a remote repositorytag
: 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.
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 |
Dependencies
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 viatop-src-dir
.
Get it
darcs get --partial http://code.haskell.org/~conal/code/cabal-make
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.
To do
- Eliminate the restrictions/assumptions listed in #Use guidelines.