diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,15 @@ +0.2.3 +===== + +* Show the help options in the options summary message. + +* Add `-?` as short version of for `--help` in addition to `-h`. + +* Remove `showHelpOnError` and `disambiguate` from option parser preferences. + +* Added file `INSTALL_ON_WINDOWS.md` with installation instructions for + windows to the package. + 0.2.2 ===== diff --git a/INSTALL_ON_WINDOWS.md b/INSTALL_ON_WINDOWS.md new file mode 100644 --- /dev/null +++ b/INSTALL_ON_WINDOWS.md @@ -0,0 +1,118 @@ +When using the `Setup.hs` script from the *configuration-tools* package +with a source build from a git repository a git binary must be available +in the `PATH` environment of the installation command. This is, for instance, +the case for the test-suite of the *configuration-tools* package itself. + +The first step in the following description installs a git binary that +is globally available in the system. Steps two through seven explain +how to setup a Haskell build environment on a Windows system in general. +Those steps are not specific to the *configuration-tools* package. Steps +eight and nine explain how to install and test the *configuration-tools* +package. + +Windows +======= + +The following steps make use of the `Git Bash` terminal. Beside of being +convenient for users that are familiar with POSIX systems, it is also a +requirement for installing the *network* package, which is a dependency of +*cabal*. Most other Haskell packages can be installed from a windows shell +(PowerShell or cmd shell) as well. + +1. Install Git from: [Git for windows](http://git-scm.com/download/win) + + During the installation, when ask about the environment settings, + select the second option that makes the git command available at + the windows shell prompt. Otherwise the git binary is available + only when `cabal` is executed from the *Git Bash* terminal. + +2. Download the + [GHC binary distribution for windows](http://www.haskell.org/ghc/dist/7.8.3/ghc-7.8.3-x86_64-unknown-mingw32.tar.bz2) + and unpack it in a convenient place. + + In the following we assume that it was unpacked in `C:\` into the default directory `C:\ghc-7.8.3`. + +3. Obtain a windows cabal binary, for example from the Haskell Platform distribution + or a previous GHC installation (the version doesn't matter). + +4. Open the *Git Bash* terminal. A link to it should have been created in the start menu + during the Git installation. + +5. Include the `bin` directory and `mingw/bin` directory from the GHC binary distribution into + the `PATH` environment: + + ~~~{.sh} + export PATH=/c/ghc-7.8.3/bin:/c/ghc-7.8.3/mingw/bin:$PATH + ~~~ + +6. Make sure a cabal binary is available in the `PATH` + + ~~~{.sh} + which cabal + ~~~ + + and check that `ghc`, `ld`, and `gcc` are used from the respective directories under + `/c/ghc-7.8.3/*`: + + ~~~{.sh} + which ghc + which ld + which gcc + ~~~ + +7. Install an updated version of `cabal`: + + ~~~{.sh} + cabal update + cabal install cabal-install + ~~~ + + Make sure that the location into which the resulting cabal binary is installed + (the location is configured in `~/AppData/Roaming/cabal/config` and it is also + printed to the installation logs) is in your `PATH`. + + Check that you are now using the most recent version of cabal: + + ~~~{.sh} + which cabal + cabal --version + ~~~ + +8. Install the *configuration-tools* package from Hackage: + + ~~~{.sh} + cabal install configuration-tools --enable-tests + ~~~ + + Alternativly, you my clone and install it from + [GitHub](https://github.com/alephcloud/hs-configuration-tools.git): + + ~~~{.sh} + git clone https://github.com/alephcloud/hs-configuration-tools.git + cd hs-configuration-tools + cabal install --enable-tests + ~~~ + +9. When you installed *configuration-tools* from source you may run the tests + from within the package directory as follows: + + ~~~{.sh} + cabal test + ~~~ + + You can run the test with different command line options using cabals `--test-option` + flag. For instance[^1]: + + ~~~{.sh} + cabal test --show-details=always --test-option=--help + cabal test --show-details=always --test-option=--long-info + ~~~ + + [^1]: Note: the windows terminal reacts ungracefully to Unicode characters. In order to have + it at least not crash the program you should run the following command before you + exectute any command that may print unicode characters (like the copyright symbol in the + test examples): + + ~~~{.sh} + chcp.com 65001 + ~~~ diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -411,82 +411,75 @@ `examples/Trivial.hs` from this package: ~~~{.shell} -trivial-0.1 (package configuration-tools-0.1 revision 080c27a) +trivial-0.2.3 (package configuration-tools-0.2.3 revision 83634a3) Copyright (c) 2014 AlephCloud, Inc. Author: Lars Kuhtz License: MIT Homepage: https://github.com/alephcloud/hs-configuration-tools -Build with: ghc-7.8.2 (x86_64-osx) +Build with: ghc-7.8.3 (x86_64-osx) Build flags: Dependencies: - Cabal-1.21.0.0 [BSD3, 2003-2006, Isaac Jones 2005-2011, Duncan Coutts] + Cabal-1.20.0.1 [BSD3, 2003-2006, Isaac Jones 2005-2011, Duncan Coutts] MonadRandom-0.1.13 [OtherLicense] aeson-0.7.0.6 [BSD3, (c) 2011-2014 Bryan O'Sullivan (c) 2011 MailRank, Inc.] ansi-terminal-0.6.1.1 [BSD3] ansi-wl-pprint-0.6.7.1 [BSD3] array-0.5.0.0 [BSD3] - attoparsec-0.11.3.4 [BSD3] - base-4.7.0.0 [BSD3] + attoparsec-0.12.1.0 [BSD3] + base-4.7.0.1 [BSD3] base-unicode-symbols-0.2.2.4 [BSD3, 2009–2011 Roel van Dijk ] + bifunctors-4.1.1.1 [BSD3, Copyright (C) 2008-2013 Edward A. Kmett] rts-1.0 [BSD3] bytestring-0.10.4.0 [BSD3, Copyright (c) Don Stewart 2005-2009, (c) Duncan Coutts 2006-2013, (c) David Roundy 2003-2005, (c) Jasper Van der Jeugt 2010, (c) Simon Meier 2010-2013.] comonad-4.2 [BSD3, Copyright (C) 2008-2013 Edward A. Kmett, Copyright (C) 2004-2008 Dave Menendez] - conduit-1.1.2.1 [MIT] + conduit-1.1.6 [MIT] containers-0.5.5.1 [BSD3] - contravariant-0.5.1 [BSD3, Copyright (C) 2007-2013 Edward A. Kmett] + contravariant-0.6 [BSD3, Copyright (C) 2007-2014 Edward A. Kmett] deepseq-1.3.0.2 [BSD3] directory-1.2.1.0 [BSD3] - distributive-0.4.3.2 [BSD3, Copyright (C) 2011-2014 Edward A. Kmett] - dlist-0.7.0.1 [BSD3, 2006-2009 Don Stewart, 2013 Sean Leather] - either-4.1.2 [BSD3, Copyright (C) 2008-2014 Edward A. Kmett] + distributive-0.4.4 [BSD3, Copyright (C) 2011-2014 Edward A. Kmett] + dlist-0.7.1 [BSD3, 2006-2009 Don Stewart, 2013 Sean Leather] + either-4.3.0.1 [BSD3, Copyright (C) 2008-2014 Edward A. Kmett] errors-1.4.7 [BSD3, 2012, 2013 Gabriel Gonzalez] exceptions-0.6.1 [BSD3, Copyright (C) 2013-2014 Edward A. Kmett Copyright (C) 2012 Google Inc.] filepath-1.3.0.2 [BSD3] + free-4.9 [BSD3, Copyright (C) 2008-2013 Edward A. Kmett] ghc-prim-0.3.1.0 [BSD3] hashable-1.2.2.0 [BSD3] integer-gmp-0.5.1.0 [BSD3] - lifted-base-0.2.2.2 [BSD3, (c) 2011-2012 Bas van Dijk, Anders Kaseorg] + lifted-base-0.2.3.0 [BSD3, (c) 2011-2012 Bas van Dijk, Anders Kaseorg] mmorph-1.0.3 [BSD3, 2013 Gabriel Gonzalez] monad-control-0.3.3.0 [BSD3, (c) 2011 Bas van Dijk, Anders Kaseorg] mtl-2.1.3.1 [BSD3] nats-0.2 [BSD3, Copyright (C) 2011-2014 Edward A. Kmett] old-locale-1.0.0.6 [BSD3] - optparse-applicative-0.8.1 [BSD3, (c) 2012 Paolo Capriotti ] + optparse-applicative-0.9.0 [BSD3, (c) 2012 Paolo Capriotti ] + prelude-extras-0.4 [BSD3, Copyright (C) 2011-2014 Edward A. Kmett] pretty-1.1.1.1 [BSD3] primitive-0.5.3.0 [BSD3, (c) Roman Leshchinskiy 2009-2012] process-1.2.0.0 [BSD3] + profunctors-4.0.4 [BSD3, Copyright (C) 2011-2014 Edward A. Kmett] random-1.0.1.1 [BSD3] resourcet-1.1.2.2 [BSD3] - safe-0.3.4 [BSD3, Neil Mitchell 2007-2014] - scientific-0.3.2.0 [BSD3] - semigroupoids-4.0.2 [BSD3, Copyright (C) 2011-2013 Edward A. Kmett] - semigroups-0.14 [BSD3, Copyright (C) 2011-2014 Edward A. Kmett] - syb-0.4.1 [BSD3] + safe-0.3.6 [BSD3, Neil Mitchell 2007-2014] + scientific-0.3.3.0 [BSD3] + semigroupoids-4.0.2.1 [BSD3, Copyright (C) 2011-2013 Edward A. Kmett] + semigroups-0.15.1 [BSD3, Copyright (C) 2011-2014 Edward A. Kmett] + syb-0.4.2 [BSD3] tagged-0.7.2 [BSD3, 2009-2013 Edward A. Kmett] template-haskell-2.9.0.0 [BSD3] - text-1.1.1.2 [BSD3, 2009-2011 Bryan O'Sullivan, 2008-2009 Tom Harper] + text-1.1.1.3 [BSD3, 2009-2011 Bryan O'Sullivan, 2008-2009 Tom Harper] time-1.4.2 [BSD3] transformers-0.3.0.0 [BSD3] transformers-base-0.4.2 [BSD3, 2011 Mikhail Vorozhtsov , Bas van Dijk ] - transformers-compat-0.1.1.1 [BSD3, Copyright (C) 2012 Edward A. Kmett] + transformers-compat-0.3.3.4 [BSD3, Copyright (C) 2012 Edward A. Kmett] unix-2.7.0.1 [BSD3] - unordered-containers-0.2.4.0 [BSD3, 2010-2014 Johan Tibell 2010 Edward Z. Yang] - vector-0.10.9.1 [BSD3, (c) Roman Leshchinskiy 2008-2012] + unordered-containers-0.2.5.0 [BSD3, 2010-2014 Johan Tibell 2010 Edward Z. Yang] + vector-0.10.11.0 [BSD3, (c) Roman Leshchinskiy 2008-2012] void-0.6.1 [BSD3, Copyright (C) 2008-2013 Edward A. Kmett] - yaml-0.8.8.3 [BSD3] - -Available options: - -i,--info Print program info message and exit - --long-info Print detailed program info message and exit - -v,--version Print version string and exit - --license Print license of the program and exit - -h,--help Show this help text - -p,--print-config Print the parsed configuration to standard out and - exit - -c,--config-file FILE Configuration file for backend services in YAML - fromat + yaml-0.8.8.4 [BSD3] ~~~ Configuration Types for HTTP Services and Clients diff --git a/configuration-tools.cabal b/configuration-tools.cabal --- a/configuration-tools.cabal +++ b/configuration-tools.cabal @@ -3,7 +3,7 @@ -- ------------------------------------------------------ -- Name: configuration-tools -Version: 0.2.2 +Version: 0.2.3 Synopsis: Tools for specifying and parsing configurations description: Tools for specifying and parsing configurations @@ -42,6 +42,7 @@ extra-doc-files: README.md, CHANGELOG.md + INSTALL_ON_WINDOWS.md extra-source-files: constraints @@ -53,7 +54,7 @@ source-repository this type: git location: https://github.com/alephcloud/hs-configuration-tools.git - tag: 0.2.2 + tag: 0.2.3 Library hs-source-dirs: src diff --git a/constraints b/constraints --- a/constraints +++ b/constraints @@ -11,7 +11,7 @@ bytestring ==0.10.4.0, comonad ==4.2, conduit ==1.1.6, - configuration-tools ==0.2.2, + configuration-tools ==0.2.3, containers ==0.5.5.1, contravariant ==0.6, deepseq ==1.3.0.2, diff --git a/src/Configuration/Utils.hs b/src/Configuration/Utils.hs --- a/src/Configuration/Utils.hs +++ b/src/Configuration/Utils.hs @@ -505,10 +505,18 @@ ⊕ maybe mempty O.footer _piHelpFooter where optionParser = fromMaybe (pure id) pkgInfoParser - <*> O.helper + <*> nonHiddenHelper <*> (over mainConfig <$> _piOptionParser) <*> pAppConfiguration _piDefaultConfiguration + -- the 'O.helper' option from optparse-applicative is hidden be default + -- which seems a bit weired. This option doesn't hide the access to help. + nonHiddenHelper = abortOption ShowHelpText + × long "help" + ⊕ short 'h' + ⊕ short '?' + ⊕ help "Show this help text" + -- | Run an IO action with a configuration that is obtained by updating the -- given default configuration the values defined via command line arguments. -- @@ -537,9 +545,7 @@ else mainFunction ∘ _mainConfig $ conf where mainOpts = mainOptions appInfo Nothing - parserPrefs = O.prefs - $ O.disambiguate - ⊕ O.showHelpOnError + parserPrefs = O.prefs O.disambiguate -- -------------------------------------------------------------------------- -- -- Main Configuration with Package Info @@ -627,9 +633,7 @@ else mainFunction ∘ _mainConfig $ conf where mainOpts = mainOptions appInfo (Just $ pPkgInfo pkgInfo) - parserPrefs = O.prefs - $ O.disambiguate - ⊕ O.showHelpOnError + parserPrefs = O.prefs O.disambiguate -- -------------------------------------------------------------------------- -- -- Configuration of Optional Values