Add semi-helpful readme
Getty Ritter
6 years ago
| 1 | **Potential users beware!** This is basically a glorified personal | |
| 2 | shell script (and in fact is literally a smarter Haskell | |
| 3 | reimplementation of what I used to do using shell scripts.) It's | |
| 4 | designed to do what I want, and very likely doesn't do what you want | |
| 5 | (or does it poorly or buggily.) | |
| 6 | ||
| 7 | The *charter* tool is a tool for setting up Haskell projects. It has | |
| 8 | three basic modes of operation which correspond to three kinds of | |
| 9 | projects: | |
| 10 | ||
| 11 | - `charter quick foo` creates a project called `foo` that contains a | |
| 12 | single executable whose entry point is in `src/Main.hs`. This is | |
| 13 | good for quick-and-dirty Haskell executables that need little extra | |
| 14 | scaffolding. | |
| 15 | - `charter library foo` creates a project called `foo` that | |
| 16 | contains a library whose sources are in `src`. | |
| 17 | - `charter executable foo` creates a project called `foo` that | |
| 18 | contains a binary whose entry point is in `foo/Main.hs` as well as a | |
| 19 | library whose sources are in `src`, and also adds a built-in `foo` | |
| 20 | dependency to the executable. | |
| 21 | ||
| 22 | Some of the information needed to set up these projects is grabbed | |
| 23 | from command-line tools, and in particular from `git` (the author and | |
| 24 | maintainer name and email) and from `date` (the current year for | |
| 25 | copyright information). Other pieces of information are commented out, | |
| 26 | but can also be provided via command-line flags (such as the category, | |
| 27 | synopsis, description, and license). Command-line flags can also add | |
| 28 | extra binary targets, add modules to the library, or add dependencies. | |
| 29 | ||
| 30 | Note that the flags are processed in-order and sometimes order will | |
| 31 | affect the output. | |
| 32 | ||
| 33 | # Example Usage | |
| 34 | ||
| 35 | Create a library `foo` that exposes two modules, `Data.Foo` and | |
| 36 | `Data.Bar`, and has a dependency on `bytestring`. | |
| 37 | ||
| 38 | ```bash | |
| 39 | $ charter library foo \ | |
| 40 | -m Data.Foo \ | |
| 41 | -m Data.Foo.Bar \ | |
| 42 | -a bytestring | |
| 43 | ``` | |
| 44 | ||
| 45 | Create a simple executable `cat` that depends on `text`, and has a | |
| 46 | filled-in category and synopsis | |
| 47 | ||
| 48 | ```bash | |
| 49 | $ charter quick haskat \ | |
| 50 | -a text \ | |
| 51 | -s 'The Haskcat program' | |
| 52 | -d 'Probably a pure Haskell implementation of cat, I guess?' | |
| 53 | ``` | |
| 54 | ||
| 55 | Create a library `make-it-so` which exposes the module | |
| 56 | `Web.Make.It.So` and which depends on `warp` and `wai`, and then | |
| 57 | create three executables as well: | |
| 58 | ||
| 59 | ```bash | |
| 60 | $ charter library make-it-so \ | |
| 61 | -m Web.Make.It.So | |
| 62 | -a warp | |
| 63 | -a wai | |
| 64 | -b do-this | |
| 65 | -b do-that | |
| 66 | -b do-the-other | |
| 67 | ``` |