add named rules to the README

Summary:
Also improve wording in a few places and clarify the relationship
between `PERU_DIR` and `PERU_CACHE`

Reviewers: sean

Differential Revision: https://phabricator.buildinspace.com/D100
let hg fetches print to stdout

Summary: This lets it take advantage of the new fancy display.

Reviewers: sean

Differential Revision: https://phabricator.buildinspace.com/D94
clean up the curl download logic

Summary:
Create `curl_plugin_shared.download_file` to get rid of some duplication
between curl fetch and reup. Add progress printing to this function, so
that curl now plays nicely with the fancy terminal.

Test Plan: New tests included for the shared logic.

Reviewers: sean

Differential Revision: https://phabricator.buildinspace.com/D95
let svn fetches print to stdout

Summary:
As we've done recently for hg and curl, let svn print its fetch progress
to stdout, so that the fancy display can show it.

Reviewers: sean

Differential Revision: https://phabricator.buildinspace.com/D96
add 'fetch exe' and 'reup exe' to plugin.yaml

Summary:
Previously we always used `fetch.*` and `reup.*` paths to invoke
plugins. That any-extension bit on the end was pretty messy, and it also
forced plugins supporting reup to have at least 2 script files (in
practice, at least 3). With this diff, `plugin.yaml` now requires the
`fetch exe` field, which defines the path that gets invoked. Plugins
that support reup will also define `reup exe`.

Those two exes can be the same script, in which case the script will
need to switch on the `PERU_PLUGIN_COMMAND` variable to figure out
whether it's doing a fetch or a reup. I actually prefer that overhead to
splitting up everything in different files, but I'd appreciate comments
on this. This diff only updates our plugins' `plugin.yaml` files; my
next diff will reorganize plugins into single scripts.

See https://github.com/buildinspace/peru/issues/45

Reviewers: sean

Differential Revision: https://phabricator.buildinspace.com/D97
reorganize plugins into unified scripts

Summary:
Now that plugin.yaml has the 'fetch exe' and 'reup exe' fields (and now
that we define the PERU_PLUGIN_COMMAND variable), we can reorganize all
of our plugins into single files. Since they're all fairly small
scripts, I prefer that to creating *_shared.py everywhere. The plugins
that were already one file just get some more descriptive names, like
`cp_plugin.py` instead of `fetch.py`.

I think I like the results of this diff, but I want to hear what you
think, @sean.

https://github.com/buildinspace/peru/issues/45

Reviewers: sean

Subscribers: sean

Differential Revision: https://phabricator.buildinspace.com/D98
replace asyncio.gather with a stable wrapper

Summary:
The `asyncio.gather` function kicks off tasks in random order. That
means our modules get fetched in a random order, which isn't great. (We
went through all that trouble to allow ordered imports, after all.)
`stable_gather` is a small wrapper function around `gather` that
preserves the order of its arguments.

Test Plan:
Run a sync in the peru repo and confirm that the fetches happen in
alphabetical order. Turn our imports into a YAML list and confirm that
the fetches happen in list order.

Reviewers: sean

Differential Revision: https://phabricator.buildinspace.com/D99
make git, hg, and svn print something during reup

Summary:
We were printing "git fetch" and "hg pull" as appropriate during sync,
but not during reup. Creating a little helper function makes this more
consistent.

Reviewers: sean

Differential Revision: https://phabricator.buildinspace.com/D101
update README.md with a snazzy gif!

Summary:
Also tweak wording in a couple places, and delete the stub manpage until
we decide to flesh it out.

The gif was generated from my https://github.com/oconnor663/dotfiles
repo using ffmpeg and convert (imagemagick). The relevant commands were:

```
ffmpeg -y -framerate 10 -video_size 602x338 -f x11grab -i :0.0+54,207 \
    -preset ultrafast -qp 0 out.mkv
ffmpeg -i out.mkv frame%04d.png
convert -delay 10 frame*.png -layers OptimizeFrame out.gif
```

- I used `xwininfo` to grab the dimensions info for the first command. I
  also subtracted the width of the scrollbar, measured with a screenshot
  in Gimp.
- The `-y` flag automatically says yes when prompted to overwrite an
  existing video file (this seemingly optional flag actually avoids a
  nasty bug: https://trac.ffmpeg.org/ticket/3989).
- `-qp 0` makes sure the video is recorded losslessly.
- `-preset ultrafast` skips most compression, to take load off the CPU,
  since we're recording in real time.
- `-layers OptimizeFrame` does some very clever gif magic to remove
  duplicate pixels between frames, which shrinks our gif by ~4x.

Reviewers: sean

Differential Revision: https://phabricator.buildinspace.com/D102
unbreak tests in python3.3

`contextlib.redirect_stdout` doesn't exist in 3.3. Instead of using
that, add an explicit parameter to redirect curl progress output in
tests.
comment update, now that module imports are gone

Reviewers: sean

Reviewed By: sean

Differential Revision: https://phabricator.buildinspace.com/D107
when printing errors, only add a newline if there isn't one already

Summary:
Some errors include subprocess output, which is already
newline-terminated.

Reviewers: sean

Reviewed By: sean

Differential Revision: https://phabricator.buildinspace.com/D106
start using subprocess.DEVNULL again

Summary:
We stopped using this for 3.2 compatibility, but now that we're >=3.3 we
can bring it back.

Reviewers: sean

Reviewed By: sean

Differential Revision: https://phabricator.buildinspace.com/D103
use a relative path for the README gif

Summary:
The absolute path makes other forks and branches point to the
buildinspace:master version of the gif. The relative path respects the
version of the gif in whatever repo we're looking at.

Reviewers: sean

Reviewed By: sean

Differential Revision: https://phabricator.buildinspace.com/D108
factor out create_subprocess_with_handle()

Summary:
We're about to integrate build commands with the fancy display. We need
to split out the logic that grabs output from plugin subprocesses, so
that build commands can reuse it.

Reviewers: sean

Reviewed By: sean

Differential Revision: https://phabricator.buildinspace.com/D104
turn Rule.do_build into a coroutine

Summary:
Build commands now run in parallel with fetches, so a long-running build
command won't block progress on the main thread. We still limit
ourselves to one build command at a time, to avoid thrashing the disk,
and so that we can safely forward build command output straight to the
console without interleaving.

To make this easy, we add a `get_printing_handle` to `BaseDisplay`. This
handle implements the interface of a regular display handle, but just
calls the display's `print` method instead of doing anything fancy. That
lets us share `create_subprocess_with_handle` between modules and rules
without any other changes.

Test Plan:
Added an integration test for fetch and build output that also
conveniently fails if the cache checks or locks are removed for either
rules or modules. (That causes the build or fetch to occur and print
multiple times, disrupting the output.)

Reviewers: sean

Reviewed By: sean

Differential Revision: https://phabricator.buildinspace.com/D105
setup.py

Summary:
Create a simple setup.py file from the instructions at
https://packaging.python.org/en/latest/distributing.html. The
`package_data` field doesn't seem to like directories, so we need to
walk the paths under `./peru/resources` to include everything.

Right now we're not including anything under third_party. Instead we
pull those in as dependencies from PyPI. Not sure if this is what we'll
do in the long term, but it's nice that it works.

Test Plan:
Ran `python3 setup.py install --user` and confirmed that peru works.
Then `cd tests; python3 -m unittest` to confirm that tests pass against
the installed version.

Reviewers: sean

Reviewed By: sean

Differential Revision: https://phabricator.buildinspace.com/D125
create an Arch PKGBUILD

Summary:
Also including a little script that makes it easier to package your
local copy of the sources (instead of the default, cloning a new repo to
package).

Reviewers: sean

Reviewed By: sean

Differential Revision: https://phabricator.buildinspace.com/D126
use ProactorEventLoop on Windows

Summary:
The default event loop on Windows doesn't support subprocesses, so we
need to set this. Unfortunately the event loop is a global, and there's
a bit of a race condition to set it before anything tries to read it.
(In particular, instantiating an asyncio Lock or Semaphore grabs a
reference to the global loop.) We set it here at import time, which
works fine for now, but it makes me worry that some future code
(probably in tests) isn't going to import our `async` module, and will
run into bugs as a result. I'd love to have a better place to put this.

Reviewers: sean

Reviewed By: sean

Differential Revision: https://phabricator.buildinspace.com/D109
make sure DEBUG_PARALLEL_COUNT is decremented on a plugin error

Summary:
This global is used in tests, to keep track of how many jobs run at
once. Jobs are supposed to increment it when they start and decrement it
when they finish. But if the plugin returned an error code, we were
throwing and failing to decrement that code.

This didn't repro for me locally, because the only tests that checked
the counter were happening early in my test run, but it caused Travis
failures because of a quirk in test run order.

This diff fixes the issue by putting the decrement in a finally clause,
and it extends the plugin tests so that all of them sanity check this
counter.

Reviewers: sean

Reviewed By: sean

Differential Revision: https://phabricator.buildinspace.com/D130