brainstorming ways to stabalize Cabal interface?

[Isaac Jones]

Greetings.  I'm keen to try to stabalize more of the Cabal interface,
but I'm not sure the best way to go about that.  I started a wiki page
to start to document what is stable and what is not.  Eventually this
should move into the end-user documentation:

http://hackage.haskell.org/trac/hackage/wiki/StableInterfaces

Does anyone have clever ideas for how to go about pushing these
interfaces toward stability?  Do we just need to declare that certain
things are unstable for the near-term (and possibly implement the
eternal compatibility in theory idea[1]) and continue to experiment
with them until they seem done enough?  Do we stare at them very hard?

Below[2] are my thoughts about what we _know_ to be stable, and the
types for the new hooks interface.


peace,

  isaac



[1] http://www.haskell.org/tmrwiki/EternalCompatibilityInTheory 

[2] Here's a summary of the bits of interface that need to be
    stabalized, or are already stabalized.

Stable Commands

    * ./setup configure
          o --prefix
          o --user
          o --ghc, --hugs
          o --verbose 
    * ./setup build
    * ./setup install 

Unstable Commands
    * everything else.  well, they're really _pretty_ stable.

Stable functions

    * defaultMain
    * defaultMainWithHooks defaultUserHooks
          o but regular defaultMainWithHooks isn't stable since userHooks changes. 

Unstable functions

    * Various utility functions 
    * UserHooks

runTests :: Args -> Bool -> PackageDescription -> LocalBuildInfo -> IO ExitCode, -- ^Used for @.\/setup test@
readDesc :: IO (Maybe PackageDescription), -- ^Read the description file
hookedPreProcessors :: [ PPSuffixHandler ],
   -- ^Custom preprocessors in addition to and overriding 'knownSuffixHandlers'.
hookedPrograms :: [Program],
   -- ^These programs are detected at configure time.  Arguments for them are added to the configure command.
  -- |Hook to run before configure command
preConf  :: Args -> ConfigFlags -> IO HookedBuildInfo,
-- |Over-ride this hook to get different behavior during configure.
confHook :: PackageDescription -> ConfigFlags -> IO LocalBuildInfo,
 -- |Hook to run after configure command
postConf :: Args -> ConfigFlags -> PackageDescription -> LocalBuildInfo -> IO ExitCode,
...
   * Everything else

peace,

  isaac