This is the beginning of a manual for franchise. It consists of several small pages describing certain aspects of franchise, each of which doubles as a test in the test suite.
To add new tests (or equivalently, new documentation), just add a new file
doc/filename.text.in, and when the documentation is rebuilt, it will
appear in this index. The documentation is generated in the lexigraphic
order according to file names. To this end, I've prefixed the files with
two-digit sequences. Please try to arrange it so the more readable docs
are at the beginning of the list.
Here are the actual docs. I'm trying to arrange things in a reasonable order, so you can read the links one at a time and learn to use franchise. Ultimately, we should haddock the sources and link into the haddock from here.
Franchise itself is a library for writing configure/build scripts. This
manual is goal-oriented, rather than API-oriented, meaning that we discuss
how to achieve goals you might have, introducing functions as they are
needed. At the same time, we give scripts demonstrating how the resulting
Setup.hs scripts behave.
In general, franchise scripts behave analogously to configure scripts
generated by autoconf, except that they are capable not only of
configuring your program, but also of building it, so a one sense,
franchise scripts serve as a combination of a configure script with a
makefile.
Franchise is a configuration and build system for Haskell projects. The configure system employed in franchise is designed to be easily forward and backward compatible, meaning that you shouldn't need to change your Setup.hs file in order to compile with a new version of ghc, and if you do need to make a change in your Setup.hs file, it shouldn't force users who have an older version of franchise and/or ghc to upgrade either their compiler or their copy of franchise. The latter goal is really only going to be realized if and when a stable version of franchise is released... as it is currently is something of a pre-alpha state (but useable, for instance, for compiling darcs).
One goal of franchise is to not require developers to provide redundant information. For instance, you've already listed all the modules you use, and ghc already knows which modules are present in which packages, so there's in general no need for you to list the packages that you require, much less their versions. This enhances both forwards and backwards compatibility, and just plain makes your life easier. If a particular module is provided by more than one package, you may need to disambiguate, but that's not the common case.
Perhaps also worth mentioning is that franchise supports parallel builds similar to make -j. Currently the number of simultaneous builds is fixed at four. Franchise does not, however, compute an optimized parallel build order, with the result that on the darcs repository a franchise build is a few percent slower than make -j4.
Franchise is currently ghc-specific and won't run on Windows, but patches to extend either of these limitations would be welcome. It also currently won't work when any flags contain space characters (e.g. with --prefix="/home/user/My stuff"), but the fix for lack of space support is the same as the fix for Windows support, so far as I can tell.
The package name "franchise" stands for "Fun, relaxing and calming Haskell into Saturday evening." It is also something of an antonym of "cabal," since "franchise" means the right to vote. Which also fits in with the concept of allowing the code to decide on its own dependencies. Franchise is made up of some pretty ugly code, with a small amount of pretty beautiful code. But it was all code that was fun and relaxing to write.
It you want to have argumentative, stressful conversations, please don't do so on the subject of fun, relaxing and calming code.
Note: franchise is almost entirely undocumented. It does only export a couple of dozen functions, but still might be hard to learn to use. This is because writing documentation is not as fun, relaxing or calming as writing Haskell. Also, franchise is not yet at the stage where it's likely to be useful to you without any features added, unless you've got a very simple project, in which case you should be able to pretty easily copy and modify an existing franchise Setup.hs file.
Simple use of the C preprocessor
A foreign function interface wrapper
Using replace to generate source files
Building both a package and an executable
Using hpc to test program coverage
requireModule only checks once for the module
Using requireExporting to select a module with a particular API