cabal init

During the Hackathon in Edinburgh last year, Benedikt Huber and I worked hard on adding a new feature to cabal-install. It eventually made its way into the codebase and has now been a part of cabal-install since version 0.8.0. However, it seems that lots of people still don’t know about it, so I thought I’d write a quick post about it.

What do you do when you want to create a new Cabalized package? If you’re like me, in the past you’ve probably copy-and-pasted the .cabal file from a different project and edited it. And the first .cabal file you ever made, you probably copy-and-pasted from someone else’s project. This works fine up to a point, but it’s annoying, and you never end up learning about great new features that Cabal now supports, or about things you’ve been doing that are now deprecated. Wouldn’t it be great if the initial setup for a Cabal project could be generated for you?

The solution is a new mode for the cabal command line tool, cabal init, which interactively prompts you for some information and creates a default .cabal file and related package stuff for you. Without further ado, let’s see it in action!

$ mkdir myproject
$ cd myproject
$ cat > Foo.hs
module Foo where

x = 3

This is going to be the best package ever!

$ cabal init
Package name [default "myproject"]?           
Package version [default "0.1"]? 
Please choose a license:
   1) GPL
   2) GPL-2
   3) GPL-3
   4) LGPL
   5) LGPL-2.1
   6) LGPL-3
 * 7) BSD3
   8) BSD4
   9) MIT
  10) PublicDomain
  11) AllRightsReserved
  12) OtherLicense
  13) Other (specify)
Your choice [default "BSD3"]? 
Author name [default "Brent Yorgey"]? 
Maintainer email [default "byorgey@cis.upenn.edu"]? 
Project homepage/repo URL? http://best.project.evar/
Project synopsis? The best package ever!  Defines 3 so you don't have to.
Project stability:
   1) Stable
   2) Provisional
 * 3) Experimental
   4) Alpha
   5) Other (specify)
Your choice [default "Experimental"]? 
Project category:
   1) Codec
   2) Concurrency
   3) Control
   4) Data
   5) Database
   6) Development
   7) Distribution
   8) Game
   9) Graphics
  10) Language
  11) Math
  12) Network
  13) Sound
  14) System
  15) Testing
  16) Text
  17) Web
  18) Other (specify)
Your choice? 11
What does the package build:
   1) Library
   2) Executable
Your choice? 1
Generating LICENSE...
Generating Setup.hs...
Generating myproject.cabal...

You may want to edit the .cabal file and add a Description field.

Notice how it automatically guessed the project name and my name and email. (Actually, I’m not even sure how it did that! Fancy!) And here’s what it generated. Notice that the module Foo is listed as an export; it automatically looks through the current directory and any subdirectories for things that look like modules to be exported.

$ cat myproject.cabal
-- myproject.cabal auto-generated by cabal init. For additional
-- options, see
-- http://www.haskell.org/cabal/release/cabal-latest/doc/users-guide/authors.html#pkg-descr.
-- The name of the package.
Name:                myproject

-- The package version. See the Haskell package versioning policy
-- (http://www.haskell.org/haskellwiki/Package_versioning_policy) for
-- standards guiding when and how versions should be incremented.
Version:             0.1

-- A short (one-line) description of the package.
Synopsis:            The best package ever!  Defines 3 so you don't have to.

-- A longer description of the package.
-- Description:         

-- URL for the project homepage or repository.
Homepage:            http://best.project.evar/

-- The license under which the package is released.
License:             BSD3

-- The file containing the license text.
License-file:        LICENSE

-- The package author(s).
Author:              Brent Yorgey

-- An email address to which users can send suggestions, bug reports,
-- and patches.
Maintainer:          byorgey@cis.upenn.edu

-- A copyright notice.
-- Copyright:           

-- Stability of the pakcage (experimental, provisional, stable...)
Stability:           Experimental

Category:            Math

Build-type:          Simple

-- Extra files to be distributed with the package, such as examples or
-- a README.
-- Extra-source-files:  

-- Constraint on the version of Cabal needed to build this package.
Cabal-version:       >=1.2


Library
  -- Modules exported by the library.
  Exposed-modules:     Foo

  -- Packages needed in order to build this package.
  -- Build-depends:       

  -- Modules not exported by this package.
  -- Other-modules:       

  -- Extra tools (e.g. alex, hsc2hs, ...) needed to build the source.
  -- Build-tools:         

Notice that all the fields are commented so you know what they are for, and why you might want to edit them later. For power users who don’t want all the comments there are the --noComments and --minimal flags; consult cabal init --help for a full list of options.

Even in making this post I thought of a bunch of things that could be improved, so there’s still work to be done, but I think it’s quite usable in its current state! Give it a try and let me know of any bugs or feature requests!