Includes improvments and function documentation for all modules (in
alphabetical order) up to rebar_core, and may have included more in
other modules as I saw fit to dig and understand more of the internals.

In some cases, mv will throw a warning, while still moving the files
correctly and returning a 0 return code:

"mv: can't preserve ownership of ... Permission denied".

By default rebar3 displays compiler sources as absolute paths in their
original location, which is under the build dir.

This change introduces an option 'compiler_source_format' to format
sources in two alternative ways:

    relative
    absolute

When either 'relative' or 'absolute' are specified, the file is
resolved to its original location when it is a link. When 'relative'
is specified, the path is displayed relative to the current working
directory. When 'absolute' is specified, the path is absolute.

The default value is 'unchaged' which leaves the compiler source
unchanged.

This is arguably too flexible as I suspect most people would opt for
'relative' all the time - it's the most compact representation of the
file and is sufficient to find the source given cwd. The change
however is meant to introduce the change gradually, preserving
existing behavior and giving users a choice for formats.

In time perhaps the default can be changed to 'relative' - but still
allowing users to revert to the other two options ('absolutel' and
'unchanged') as needed.

- robocopying a directory into another directory recursively expects the
  directory name to be properly mapped onto the destination, otherwise
  all the files are copied into the given path. This patches things so
  a directory-to-directory robocopy works as expected in a linux mindset
  so tests pass
- the test for canonical paths didn't expect a windows environment at
  all; the test (and library) is modified to be consistent in that
  environment: always with a native format and with proper support of
  drive letters.

`reduce_path/1` -> `canonical_path/1`
`relative_path/2` -> `path_from_ancestor/2`

add tests

This patch forces write_file_if_contents_differ/2 to use raw bytes as
when writing files. This fixes an issue where UTF-8 characters are
processed and written back as ISO-8859-1 into the file, which makes it
impossible to use UTF-8 characters in .app.src files.

Linking message will only be printed the first time the link or copy
actually happens.

Note:

rebar_file_utils:symlink_or_copy will now return 'exists'
instead of ok, if it did nothing because the link exists.

Nothing was checking the return value yet, so seemed reasonable.

Basic escaping is done only. Fancy hex sequences are not covered, but
this should otherwise take care of the most common issues.

Fixes #497

(in `rebar_file_utils`)

While at it, improve the error message printed by rebar_utils:sh/2.

'Erlang' projects that do not contain any erlang files (Joxa, LFE,
Elixir, etc) break the eunit task. It attempts to copy an empty list
of source files to the .eunit directory. This change makes copying an
empty list a simple no-op.

Add flags to rebar_utils:sh to control output and error handling.
Replace calls to os:cmd with calls to rebar_utils:sh.

Modify rm_rf and cp_r to work when {win32,_} = os:type().
Simplify rm_rf to only accept one filename, directoryname or wildcard.
Add unit tests to ensure a similar behaviour on windows and unix.

Thanks to tuncer for guidance and feedback.

mkdir_p/1 and ln_sf/2.