hup-0.3.0.0: README.md
# hup [](https://hackage.haskell.org/package/hup) [](https://travis-ci.org/phlummox/hup)
Small program for building and uploading packages and documentation
built with `stack` to a hackage server; a Haskellified version of
[phadej's script](https://github.com/phadej/binary-orphans/blob/master/hackage-docs.sh),
which is a stack-enabled version of [ekmett's script](https://github.com/ekmett/lens/blob/master/scripts/hackage-docs.sh).
In addition to `stack`, it requires the `cabal` executable
(but will install an appropriate `cabal` if it doesn't find one in the
binaries for the package snapshot your project is using).
## Installation
Install in the standard Stack way with `stack install hup`.
## Quick usage
Try:
~~~
$ cd /path/to/my/project
$ stack build
$ hup packboth -u myHackageUserID -p myHackagePassword
$ hup docboth -u myHackageUserID -p myHackagePassword
~~~
## Usage
* `hup [COMMAND] ... [OPTIONS]`
Build and/or upload packages or documentation to a hackage server. A server
url should be of the format `PROTOCOL://SERVER[:PORT]/`, and defaults to
`https://hackage.haskell.org/` if not specified.
A password can also be given in the `PASSWORD` environment variable instead
of on the command line.
'hup --help=all' will give help for all commands.
* Commands:
packup Upload FILE as a package (or candidate package).
docbuild Build documentation for a package.
docup Upload FILE as documentation.
docboth Build and upload documentation for a package.
* Common flags:
-v --verbose be verbose
-h --help Display help message. '--help=all' will display help
for all commnds. '--help=bash' will output code for
bash command-line completion.
-V --version Print version information
--numeric-version Print just the version number
* `hup packup [OPTIONS] FILE`
Upload FILE as a package (or candidate package).
Flags:
-s --server=URL
-c --candidate
-u --user=USER
-p --password=PASSWORD
* `hup docbuild [OPTIONS]`
Build documentation for a package.
Flags:
-e --executables Run haddock for Executables targets
-t --tests Run haddock for Test Suite targets
-i --internal Run haddock for internal modules and include
all symbols
--haddock-arguments=ARGS extra args to pass to haddock
-q --quick quick build - don't build docco for
dependencies (links will be broken)
* `hup docup [OPTIONS] FILE`
Upload FILE as documentation.
Flags:
-s --server=URL
-c --candidate
-u --user=USER
-p --password=PASSWORD
* `hup docboth [OPTIONS]`
Build and upload documentation for a package.
Flags:
-e --executables Run haddock for Executables targets
-t --tests Run haddock for Test Suite targets
-i --internal Run haddock for internal modules and include
all symbols
--haddock-arguments=ARGS extra args to pass to haddock
-q --quick quick build - don't build docco for
dependencies (links may be broken)
-s --server=URL
-c --candidate
-u --user=USER
-p --password=PASSWORD
## Troubleshooting
### I get an error during upload that says "...: does not exist (no such protocol name: tcp)"
This is not actually a bug in `hup`, but is found in e.g. Docker containers
that don't have all the packages needed for networking - see e.g.
[here](https://stackoverflow.com/questions/46322773/yesod-app-in-docker-container-cant-make-network-requests) on StackOverflow.
You will need to install networking packages appropriate for your distro - on Ubuntu, something like ca-certificates, libgnutls28 (or another version of the GNU TLS library), and netbase.
### I get some sort of error when building documents that says "...haddock: internal error: ... hGetContents: invalid argument (invalid byte sequence)"
Again, this isn't actually a bug in `hup`, but happens (e.g. in Docker
containers) when the system locale is not properly set up (see a bug report
[here](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=871839) arising from a
similar issue). Annoyingly, `haddock` depends on the locale being properly set,
though it doesn't really seem necessary.
Try running `locale-gen "en_US.UTF-8"` to generate an appropriate UTF-8
locale, and `export LC_ALL="en_US.UTF-8"` so that the locale can be found
from environment variables.
## Bash command-line completion
To enable bash command-completion:
Run
hup --help=bash > hup.complete
then either "`source hup.complete`" or "`. hup.complete`".
## Defaults
Uses "`https://hackage.haskell.org/`" as the default server location,
but see the `DefaultServerUrl` module if you want to patch this to
something else before installing.
## Bugs and limitations
- Not yet tested on MS Windows or MacOS