Skip to content

Latest commit

 

History

History
177 lines (120 loc) · 5.76 KB

README.pmd

File metadata and controls

177 lines (120 loc) · 5.76 KB
Raw

hup Hackage version

Build Status Windows build status

Small program for building and uploading packages and documentation built with the stack build tool to a hackage server.

For instance, to build and upload package documentation to https://hackage.haskell.org/ for a package candidate:

$ hup docboth --candidate --user myHackageUserID --password myHackagePassword

Instead of providing a password on the command line, you can set the HUP_HACKAGE_PASSWORD environment variable and hup will use that as the password.

In addition to stack, hup 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

The recommended install method is to run:

$ stack --resolver=lts-11 build --copy-bins hup

On Linux, this will install hup to your ~/.local/bin directory -- ensure that it's on your PATH, and you're good to go.

Quick usage

Try:

$ cd /path/to/my/project
$ stack build
$ hup packboth -u myHackageUserID -p myHackagePassword
$ hup docboth -u myHackageUserID -p myHackagePassword

Usage

from subprocess import run, PIPE
res = run(["./hup", "--help"], stdout=PIPE, encoding="utf8")

global_docco = []

indentAmount = 0
for idx, line in enumerate(res.stdout.split("\n")[2:]):
  if idx == 0:
    line = f"`{line}`"

  if line == "Commands:":
    indentAmount = 6

  if line and (not line[0].isspace()):
    global_docco.append("* " + line + "\n")
  else:
    global_docco.append((' ' * indentAmount) + line)

print("\n".join(global_docco))

'--help=bash' will output code for bash command-line completion.

Subcommand details

from subprocess import run, PIPE

cmds = ["packbuild", "packup", "packboth", "docbuild", "docup", "docboth"]

for cmd in cmds:
  res = run(["./hup", cmd, "--help"], stdout=PIPE, encoding="utf8")

  global_docco = []

  indentAmount = 0
  for idx, line in enumerate(res.stdout.split("\n")[2:]):
    if idx == 0:
      line = f"* `{line}`"

    if line == "Common flags:":
      break

    if idx == 3:
      indentAmount = 2

    if line and (line.strip()[0] == '-'):
      indentAmount = 3

    if line and (not line[0].isspace()):
      global_docco.append((' ' * indentAmount) + line + "\n")
    else:
      global_docco.append((' ' * indentAmount * 2) + line)

  print("\n".join(global_docco))

Library API

For documentation of the library, see the Hackage documentation.

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 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 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

  • Some very basic tests of library and app functionality are run on MS Windows and MacOS virtual machines using GitHub and Appveyor's CI/CD capabilities, but no extensive testing on those platforms is performed.

Feature requests

So that actual bugs and defects aren't cluttered by other issues, proposed features and feature requests are maintained as closed issues on GitHub with the labels "enhancement" and "incomplete" (see here).

Credits

hup is a Haskellified version of Oleg Grenrus's script, which is a stack-enabled version of Eric Mertens's script.